Vapora/kubernetes/README.md

# VAPORA Kubernetes Manifests

Vanilla Kubernetes deployment manifests for VAPORA v1.0 (non-Istio).

## Overview

These manifests deploy the complete VAPORA stack:
- SurrealDB (StatefulSet with persistent storage)
- NATS JetStream (Deployment with ephemeral storage)
- Backend API (2 replicas)
- Frontend UI (2 replicas)
- Agents (3 replicas)
- MCP Server (1 replica)
- Ingress (nginx)

## Prerequisites

1. Kubernetes cluster (1.25+)
2. kubectl configured
3. nginx ingress controller installed
4. Storage class available for PVCs
5. (Optional) cert-manager for TLS

## Quick Deploy

```bash
# 1. Create namespace
kubectl apply -f 00-namespace.yaml

# 2. Update secrets in 03-secrets.yaml
# Edit the file and replace all CHANGE-ME values

# 3. Apply all manifests
kubectl apply -f .

# 4. Wait for all pods to be ready
kubectl wait --for=condition=ready pod -l app -n vapora --timeout=300s

# 5. Get ingress IP/hostname
kubectl get ingress -n vapora
```

## Manual Deploy (Ordered)

```bash
kubectl apply -f 00-namespace.yaml
kubectl apply -f 01-surrealdb.yaml
kubectl apply -f 02-nats.yaml
kubectl apply -f 03-secrets.yaml
kubectl apply -f 04-backend.yaml
kubectl apply -f 05-frontend.yaml
kubectl apply -f 06-agents.yaml
kubectl apply -f 07-mcp-server.yaml
kubectl apply -f 08-ingress.yaml
```

## Secrets Configuration

Before deploying, update `03-secrets.yaml` with real credentials:

```yaml
stringData:
  jwt-secret: "$(openssl rand -base64 32)"
  anthropic-api-key: "sk-ant-xxxxx"
  openai-api-key: "sk-xxxxx"
  gemini-api-key: "xxxxx"  # Optional
  surrealdb-user: "root"
  surrealdb-pass: "$(openssl rand -base64 32)"
```

## Ingress Configuration

Update `08-ingress.yaml` with your domain:

```yaml
rules:
- host: vapora.yourdomain.com  # Change this
```

For TLS with cert-manager:

```yaml
annotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"
tls:
- hosts:
  - vapora.yourdomain.com
  secretName: vapora-tls
```

## Monitoring

```bash
# Check all pods
kubectl get pods -n vapora

# Check services
kubectl get svc -n vapora

# Check ingress
kubectl get ingress -n vapora

# View logs
kubectl logs -n vapora -l app=vapora-backend
kubectl logs -n vapora -l app=vapora-agents

# Check health
kubectl exec -n vapora deploy/vapora-backend -- curl localhost:8080/health
```

## Scaling

```bash
# Scale backend
kubectl scale deployment vapora-backend -n vapora --replicas=3

# Scale agents
kubectl scale deployment vapora-agents -n vapora --replicas=5

# Scale frontend
kubectl scale deployment vapora-frontend -n vapora --replicas=3
```

## Troubleshooting

### Pods not starting

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

# Describe pod
kubectl describe pod -n vapora <pod-name>

# Check logs
kubectl logs -n vapora <pod-name>
```

### Database connection issues

```bash
# Check SurrealDB is running
kubectl get pod -n vapora -l app=surrealdb

# Test connection
kubectl exec -n vapora deploy/vapora-backend -- \
  curl -v http://surrealdb:8000/health
```

### NATS connection issues

```bash
# Check NATS is running
kubectl get pod -n vapora -l app=nats

# Check NATS logs
kubectl logs -n vapora -l app=nats

# Monitor NATS
kubectl port-forward -n vapora svc/nats 8222:8222
open http://localhost:8222
```

## Uninstall

```bash
# Delete all resources in namespace
kubectl delete namespace vapora

# Or delete manifests individually
kubectl delete -f .
```

## Notes

- SurrealDB data is persisted in PVC (20Gi)
- NATS uses ephemeral storage (data lost on pod restart)
- All images use `latest` tag - update to specific versions for production
- Default resource limits are conservative - adjust based on load
- Frontend uses LoadBalancer service type - change to ClusterIP if using Ingress only

## Architecture

```
Internet
    ↓
[Ingress: vapora.example.com]
    ↓
    ├─→ / → [Frontend Service] → [Frontend Pods x2]
    ├─→ /api → [Backend Service] → [Backend Pods x2]
    ├─→ /ws → [Backend Service] → [Backend Pods x2]
    └─→ /mcp → [MCP Service] → [MCP Server Pod]

Internal Services:
    [Backend] ←→ [SurrealDB StatefulSet]
    [Backend] ←→ [NATS]
    [Agents x3] ←→ [NATS]
```

## Next Steps

After deployment:
1. Access UI at https://vapora.example.com
2. Check health at https://vapora.example.com/api/v1/health
3. Monitor logs in real-time
4. Configure external monitoring (Prometheus/Grafana)
5. Set up backups for SurrealDB PVC
6. Configure horizontal pod autoscaling (HPA)