# Iris Kubernetes Deployment

Kubernetes manifests for deploying the Iris AI Assistant Platform using
Kustomize.

## Directory Structure

```
iris/
├── kustomization.yaml       # Root entrypoint, delegates to base/
├── base/                    # Base configuration for all environments
│   ├── kustomization.yaml   # Main deployable base
│   ├── rbac.yaml            # Service accounts and roles
│   ├── resource-quotas.yaml # Namespace resource limits
│   ├── limit-ranges.yaml    # Container resource defaults
│   ├── network-policies.yaml # Network segmentation
│   ├── priority-classes.yaml # Pod scheduling priorities
│   ├── namespaces/          # iris, iris-data namespaces
│   ├── services/            # Individual service deployments
│   └── autoscaling/         # HPA/VPA/custom/predictive scaling
└── overlays/                # Environment-specific configurations
    ├── development/       # Local/dev settings
    ├── staging/           # Staging environment
    └── production/        # Production environment
```

## Services

| Service           | Description                         | Port |
| ----------------- | ----------------------------------- | ---- |
| iris-api          | API Gateway - main entry point      | 3000 |
| iris-conversation | Conversation lifecycle management   | 3000 |
| iris-memory       | Hierarchical memory service         | 3000 |
| iris-agent        | Agent execution and tool management | 3000 |
| iris-voice        | Speech-to-text and text-to-speech   | 3000 |
| iris-worker       | Background jobs and maintenance     | 3000 |

## Deployment

### Prerequisites

1. Kubernetes cluster (1.24+)
2. kubectl configured
3. Secrets supplied by the platform secret manager or replaced from the
   deployable placeholders in `base/credentials-template.yaml`

### Create Required Secrets

```bash
kubectl create secret generic iris-secrets \
  --namespace iris \
  --from-literal=DATABASE_URL="postgresql://user:pass@postgres:5432/iris" \
  --from-literal=REDIS_URL="redis://redis:6379" \
  --from-literal=JWT_SECRET="your-jwt-secret" \
  --dry-run=client -o yaml | kubectl apply -f -

kubectl create secret generic iris-ai-secrets \
  --namespace iris \
  --from-literal=ANTHROPIC_API_KEY="sk-ant-..." \
  --from-literal=OPENAI_API_KEY="sk-..." \
  --from-literal=GOOGLE_AI_API_KEY="..." \
  --from-literal=ELEVENLABS_API_KEY="..." \
  --from-literal=CARTESIA_API_KEY="..." \
  --from-literal=DEEPGRAM_API_KEY="..." \
  --dry-run=client -o yaml | kubectl apply -f -
```

The base includes placeholder `iris-secrets` and `iris-ai-secrets` resources so
Kustomize output is complete for development clusters. Staging and production
must replace placeholder values before rollout.

### Deploy Base

```bash
kubectl apply -k infra/k8s/iris
```

### Deploy to Development Overlay

```bash
kubectl apply -k infra/k8s/iris/overlays/development
```

### Deploy to Staging

```bash
kubectl apply -k infra/k8s/iris/overlays/staging
```

### Deploy to Production

```bash
kubectl apply -k infra/k8s/iris/overlays/production
```

## Configuration

### Environment Variables

Common configuration is managed through ConfigMaps:

- `iris-common-config`: LOG_LEVEL, NODE_ENV, telemetry settings
- `iris-redis-config`: Redis connection details
- `iris-qdrant-config`: Qdrant vector DB settings

### Resource Limits

| Environment | API Replicas | Service Replicas | Worker Replicas | CPU Request | Memory Request |
| ----------- | ------------ | ---------------- | --------------- | ----------- | -------------- |
| Development | 1            | 1                | 1               | 100m        | 256Mi          |
| Staging     | 2            | 2                | 1               | 250m        | 512Mi          |
| Production  | 3            | 2-3              | 2               | 250m        | 512Mi          |

### Scaling

HorizontalPodAutoscaler is configured for all services:

- CPU target: 65-70% (service specific)
- External custom metrics from Prometheus Adapter
- Predictive metrics using 15-minute `predict_linear` forecasts
- Min replicas vary by environment
- Max replicas: up to 40 for bursty workloads

VerticalPodAutoscaler policies are also defined to optimize memory requests
without conflicting with HPA replica decisions.

## Networking

### Network Policies

- Default deny ingress to all pods
- Allow ingress controller to API
- Allow internal communication between Iris services
- Allow Iris to access data namespace (PostgreSQL, Redis, Qdrant)
- Allow Prometheus scraping

### Service Mesh (Istio)

The `iris` namespace has `istio-injection: enabled` for automatic sidecar
injection. The base kustomization also patches Iris deployments with explicit
Istio sidecar annotations and inbound port capture for port 3000.

## Monitoring

All services expose Prometheus metrics on port 3000 at `/metrics`:

```yaml
annotations:
  prometheus.io/scrape: 'true'
  prometheus.io/port: '3000'
```

## Troubleshooting

### View logs

```bash
kubectl logs -n iris deployment/iris-api
kubectl logs -n iris deployment/iris-conversation
kubectl logs -n iris deployment/iris-worker
```

### Check pod status

```bash
kubectl get pods -n iris
kubectl describe pod -n iris <pod-name>
```

### Test service connectivity

```bash
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
  curl http://iris-api.iris.svc.cluster.local:3000/health
```
