Skip to main content

Kubernetes Deployment

This guide explains how to deploy the STELLA system to Kubernetes.

Architecture​

┌─────────────────────────────────────────────────────────────┐
│                      Kubernetes Cluster                      │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                   Namespace: ai-agents                 │  │
│  │                                                         │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │  │
│  │  │  PostgreSQL  │  │   LiveKit    │  │   Backend    │ │  │
│  │  │     :5432    │  │    :7880     │  │    API       │ │  │
│  │  └──────────────┘  └──────────────┘  │    :3000     │ │  │
│  │                                       └──────────────┘ │  │
│  │                                                         │  │
│  │  ┌──────────────────────────────────────────────────┐ │  │
│  │  │        AI Agent Pods (Created On-Demand)         │ │  │
│  │  │  ┌─────────┐  ┌─────────┐  ┌─────────┐          │ │  │
│  │  │  │ Agent 1 │  │ Agent 2 │  │ Agent 3 │  ...     │ │  │
│  │  │  └─────────┘  └─────────┘  └─────────┘          │ │  │
│  │  └──────────────────────────────────────────────────┘ │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
          ↑                                     ↑
    Port Forward                          Port Forward
    localhost:3000                      localhost:7880

Prerequisites​

Required Software​

SoftwareDescriptionInstallation
DockerContainer runtimeDocker Desktop or OrbStack
kubectlKubernetes CLIbrew install kubectl (macOS)
minikubeLocal KubernetesAuto-installed by script

Configuration​

Create a .env file with your credentials:

cp .env.example .env
nano .env

Set your essential Kubernetes deployment credentials:

# AI APIs
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx

# LiveKit (WebRTC)
LIVEKIT_URL=wss://your-livekit-server.com
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret
Kubernetes Environment Variables

See namespace configuration, DNS settings, and other K8s-specific options.

Security

The .env file is gitignored. Your credentials stay local and are injected into Kubernetes secrets during deployment.

Quick Start​

Deploy Everything​

Run the all-in-one startup script:

./scripts/start-k8s.sh

This script will:

  1. Check Docker is running
  2. Install minikube (if needed)
  3. Start minikube cluster
  4. Build Docker images
  5. Deploy PostgreSQL, LiveKit, and Backend
  6. Wait for all services to be ready
  7. Start port forwarding

Access the System​

Once deployed:

ServiceURL
Backend APIhttp://localhost:3000
LiveKitws://localhost:7880
Frontendhttp://localhost:5173

Components​

PostgreSQL​

  • Deployment: postgres
  • Service: postgres:5432
  • Storage: 10Gi PersistentVolumeClaim
  • Credentials: Configured via environment

See Database Schema for the complete data model.

LiveKit Server (if self-hosted)​

  • Deployment: livekit
  • Service: livekit:7880 (HTTP), livekit:7881 (RTP/UDP)
  • Mode: Development mode (--dev flag)

Session Management Server​

  • Deployment: session-management-server
  • Service: session-management-server:3000
  • Service Account: session-management-sa (with RBAC permissions)
  • Capabilities: Creates/manages agent pods dynamically

AI Agent Pods (On-Demand)​

  • Created by: Backend server via Kubernetes API
  • Image: conversational-ai-server:latest
  • Lifecycle: Created per session, auto-deleted when stopped
  • Resources: 512Mi-2Gi RAM, 250m-1000m CPU

Useful Commands​

View Resources​

# View all resources
kubectl get all -n ai-agents

# View agent pods
kubectl get pods -n ai-agents -l app=conversational-ai-agent

# View backend logs
kubectl logs -f -n ai-agents -l app=session-management-server

# View specific agent logs
kubectl logs -n ai-agents <agent-pod-name>

Database Access​

kubectl port-forward -n ai-agents svc/postgres 5432:5432
# Then connect with: postgresql://app:app@localhost:5432/app

Scaling​

kubectl scale deployment session-management-server -n ai-agents --replicas=3

Resource Limits​

ComponentRequestLimit
PostgreSQL256Mi/250m CPU512Mi/500m CPU
LiveKit256Mi/250m CPU1Gi/1000m CPU
Backend512Mi/250m CPU1Gi/1000m CPU
Agent512Mi/250m CPU2Gi/1000m CPU

Troubleshooting​

minikube Won't Start​

# Delete and recreate cluster
minikube delete
minikube start --driver=docker --cpus=4 --memory=8192

Pods Stuck in ImagePullBackOff​

Images must be built in minikube's Docker daemon:

eval $(minikube docker-env)
docker build -t session-management-server:latest .
docker build -t conversational-ai-server:latest ./conversational-ai-server-python

Backend Can't Create Agent Pods​

# Check RBAC permissions
kubectl get role,rolebinding -n ai-agents

# Check service account
kubectl get serviceaccount -n ai-agents

# View backend logs
kubectl logs -f -n ai-agents -l app=session-management-server

Agent Pod Fails to Start​

# View pod status
kubectl get pods -n ai-agents -l app=conversational-ai-agent

# View pod logs
kubectl logs -n ai-agents <agent-pod-name>

# Describe pod for events
kubectl describe pod -n ai-agents <agent-pod-name>

Database Migration Fails​

kubectl exec -it -n ai-agents deployment/session-management-server -- npx prisma migrate deploy

Stopping the Cluster​

Stop Port Forwarding​

Press Ctrl+C in the terminal running the startup script.

Stop minikube​

minikube stop

Delete Everything​

# Delete namespace (removes all resources)
kubectl delete namespace ai-agents

# Or delete entire cluster
minikube delete

Development Workflow​

Make Code Changes​

Edit your source code in session-management-server/ or conversational-ai-server-python/.

Rebuild Images​

eval $(minikube docker-env)
docker build -t session-management-server:latest .
docker build -t conversational-ai-server:latest ./conversational-ai-server-python

Restart Deployment​

kubectl rollout restart deployment/session-management-server -n ai-agents

View Logs​

kubectl logs -f -n ai-agents -l app=session-management-server

See Also​