kubernetes/docs/DEPLOY_CHECKLIST.md

🚀 Kubernetes Deployment Checklist

✅ Pre-Deployment Checklist

Before deploying, ensure:

1. k3s is running:

   sudo systemctl status k3s
   # If not running:
   sudo systemctl start k3s
   

2. Docker images are built and imported:

   # Build images
   docker build -t fastapi-backend:latest --target api -f Dockerfile .
   docker build -t nats-worker:latest --target worker -f Dockerfile .
   
   # Import to containerd (k3s uses containerd, not Docker)
   docker save fastapi-backend:latest | sudo k3s ctr images import -
   docker save nats-worker:latest | sudo k3s ctr images import -
   

3. NATS JetStream stream is created:

   # Run the setup script
   ./setup-jetstream.sh
   # Or manually:
   python3 scripts/setup_jetstream.py
   

4. kubectl is configured:

   # On your local machine, ensure kubectl points to k3s
   kubectl get nodes
   

🚀 Deployment Steps

Option 1: Simple Deployment (Recommended)

cd kubernetes
chmod +x simple-deploy.sh
./simple-deploy.sh

Option 2: Manual Deployment

cd kubernetes/manifests

# 1. Create namespace
kubectl apply -f namespace.yaml

# 2. Create secrets
kubectl apply -f secrets.yaml

# 3. Deploy FastAPI
kubectl apply -f fastapi-deployment.yaml
kubectl apply -f fastapi-service.yaml
kubectl apply -f fastapi-hpa.yaml

# 4. Deploy Workers
kubectl apply -f worker-deployment.yaml
kubectl apply -f worker-hpa.yaml

# 5. Deploy Gateway (optional)
kubectl apply -f gateway.yaml

🔍 Verify Deployment

# Check pods
kubectl get pods -n nats-backend

# Check services
kubectl get svc -n nats-backend

# Check Gateway
kubectl get gateway -n nats-backend

# Watch pods in real-time
kubectl get pods -n nats-backend -w

# Check logs
kubectl logs -f deployment/fastapi-backend -n nats-backend
kubectl logs -f deployment/nats-worker -n nats-backend

🌐 Access Your Application

Gateway Ports:

• HTTP: Port 8201
• HTTPS: Port 8441

Note: The Gateway uses non-standard ports (8201/8441) to avoid conflicts with Traefik on port 80/443.

To access via Gateway:

# Port forward to test locally
kubectl port-forward -n nats-backend svc/fastapi-backend 8000:8000

# Then test:
curl http://localhost:8000/health

⚠️ Troubleshooting

Pods not starting?

# Check pod status
kubectl describe pod <pod-name> -n nats-backend

# Check events
kubectl get events -n nats-backend --sort-by='.lastTimestamp'

ImagePullBackOff error?

• Ensure images are imported to containerd (see step 2 above)
• Check imagePullPolicy: Never in deployments

Worker pods crashing?

• Ensure JetStream stream is created (see step 3 above)
• Check NATS connection: kubectl logs deployment/nats-worker -n nats-backend

Gateway not working?

• Gateway requires cert-manager for TLS (optional)
• HTTP should work without cert-manager
• Check Gateway status: kubectl describe gateway api-gateway -n nats-backend

📊 Monitoring

# Check HPA status
kubectl get hpa -n nats-backend

# Check resource usage
kubectl top pods -n nats-backend

🛑 Undeploy

# Delete all resources
kubectl delete namespace nats-backend

# Or delete individually
kubectl delete -f manifests/