# Iris AI Platform - Staging Infrastructure

Terraform configuration for the Iris AI Platform staging environment on AWS EKS.

## Overview

This configuration provisions:

- **VPC**: Multi-AZ network with public, private, and database subnets
- **EKS**: Kubernetes cluster with managed node groups
- **RDS**: PostgreSQL 16 with pgvector support
- **ElastiCache**: Redis 7.1 replication group
- **S3**: Buckets for conversations, memory, logs, and backups
- **ECR**: Container registries for Iris services
- **IAM**: IRSA roles for Kubernetes workloads
- **Smoke Tests**: Lambda-based health monitoring

The staging deployment manages the full Iris runtime set: `iris-api`,
`iris-conversation`, `iris-memory`, `iris-agent`, `iris-voice`, and
`iris-worker`.

## Prerequisites

1. AWS CLI configured with appropriate credentials
2. Terraform >= 1.10.0
3. S3 bucket for Terraform state (`oshun-terraform-state`)
4. DynamoDB table for state locking (`oshun-terraform-locks`)

## Usage

### Initialize

```bash
cd infra/terraform/iris/staging
terraform init
```

### Plan

```bash
terraform plan -out=tfplan
```

### Apply

```bash
terraform apply tfplan
```

### Destroy

```bash
terraform destroy
```

## Configuration

The default configuration is optimized for staging:

| Component    | Staging Configuration         |
| ------------ | ----------------------------- |
| EKS Nodes    | SPOT instances (cost savings) |
| NAT Gateway  | Single (cost savings)         |
| RDS          | db.t3.medium, Multi-AZ        |
| ElastiCache  | cache.t3.medium, 2 clusters   |
| Node Scaling | 2-6 nodes                     |

### Customization

Override defaults using `terraform.tfvars` or command-line variables:

```bash
terraform apply -var="general_node_capacity_type=ON_DEMAND"
```

## Outputs

After applying, key outputs include:

```bash
# Get cluster configuration
terraform output kubectl_config

# Get database connection info
terraform output rds_endpoint
terraform output rds_secret_arn

# Get Redis connection info
terraform output elasticache_primary_endpoint
terraform output elasticache_secret_arn

# Get ECR repository URLs
terraform output ecr_repository_urls
```

## Connecting to EKS

```bash
# Configure kubectl
eval $(terraform output -raw kubectl_config)

# Verify connection
kubectl get nodes
kubectl get pods -n iris
```

## Smoke Tests

Automated smoke tests run every 5 minutes via CloudWatch Events:

```bash
# Invoke manually
aws lambda invoke --function-name iris-staging-smoke-test response.json
cat response.json
```

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         VPC (10.110.0.0/16)                     │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    Public Subnets                           ││
│  │  ┌─────────┐    ┌─────────┐    ┌─────────┐                ││
│  │  │ NAT GW  │    │   ALB   │    │   IGW   │                ││
│  │  └─────────┘    └─────────┘    └─────────┘                ││
│  └─────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    Private Subnets                          ││
│  │  ┌─────────────────────────────────────────────────────────┐││
│  │  │                 EKS Node Group                          │││
│  │  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐      │││
│  │  │  │iris-api │ │convers. │ │ memory  │ │ agent   │      │││
│  │  │  │ voice   │ │ worker  │                                │││
│  │  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘      │││
│  │  └─────────────────────────────────────────────────────────┘││
│  └─────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                   Database Subnets                          ││
│  │  ┌─────────────────────┐  ┌─────────────────────┐          ││
│  │  │    RDS PostgreSQL   │  │   ElastiCache Redis │          ││
│  │  │    (Multi-AZ)       │  │   (Multi-AZ)        │          ││
│  │  └─────────────────────┘  └─────────────────────┘          ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
```

## Security

- All data encrypted at rest using KMS
- VPC endpoints for AWS services (ECR, S3, Secrets Manager)
- Network policies restrict pod communication
- IRSA for fine-grained IAM permissions
- Transit encryption for RDS and ElastiCache

## Monitoring

- CloudWatch Container Insights
- RDS Performance Insights
- VPC Flow Logs
- CloudWatch Alarms for:
  - RDS CPU, memory, storage, connections
  - ElastiCache CPU, memory, connections, evictions
  - Smoke test failures

## Cost Optimization (Staging)

- SPOT instances for EKS nodes
- Single NAT Gateway
- Smaller RDS and ElastiCache instance types
- Shorter log retention periods
- No deletion protection

## Deployment

Automated deployments are handled by the GitHub Actions workflow:
`.github/workflows/iris-staging-deploy.yml`

Manual deployment:

```bash
# Apply Terraform changes
terraform apply

# Deploy to Kubernetes
kubectl apply -k ../../../k8s/iris/overlays/staging
```

## Troubleshooting

### EKS Access Denied

```bash
# Verify AWS identity
aws sts get-caller-identity

# Update kubeconfig
aws eks update-kubeconfig --name iris-staging --region us-east-1
```

### Terraform State Lock

```bash
# Force unlock (use with caution)
terraform force-unlock <LOCK_ID>
```

### Pod Failures

```bash
# Check pod status
kubectl describe pod -n iris <pod-name>

# View logs
kubectl logs -n iris <pod-name>

# Check events
kubectl get events -n iris --sort-by='.lastTimestamp'
```
