Kubernetes Deployment

Overview

This guide covers deploying Praxos to a Kubernetes cluster using Azure Kubernetes Service (AKS) as an example. The concepts apply to other Kubernetes platforms with minor adjustments.

Prerequisites

Kubernetes cluster (1.24+)
kubectl configured
Docker image built and pushed to registry
Required secrets and config maps
Load balancer or ingress controller

Architecture

Namespace

Create a namespace for Praxos:

apiVersion: v1
kind: Namespace
metadata:
  name: hetairos
  labels:
    name: hetairos

Apply:

kubectl apply -f namespace.yaml

Secrets

Create Secret from Azure Key Vault

If using Azure Key Vault:

apiVersion: v1
kind: Secret
metadata:
  name: hetairos-secrets
  namespace: hetairos
type: Opaque
stringData:
  AZURE_KEY_VAULT_URL: "https://your-keyvault.vault.azure.net/"
  AZURE_TENANT_ID: "your-tenant-id"
  AZURE_CLIENT_ID: "your-client-id"
  AZURE_CLIENT_SECRET: "your-client-secret"

Or create secrets directly

apiVersion: v1
kind: Secret
metadata:
  name: hetairos-secrets
  namespace: hetairos
type: Opaque
stringData:
  MONGODB_URI: "mongodb://..."
  PORTKEY_API_KEY: "your-portkey-key"
  OPENAI_API_KEY: "your-openai-key"
  GOOGLE_API_KEY: "your-google-key"
  TELEGRAM_BOT_TOKEN: "your-telegram-token"
  DISCORD_BOT_TOKEN: "your-discord-token"
  # Add other secrets as needed

Apply:

kubectl apply -f secrets.yaml

ConfigMap

Create a ConfigMap for non-sensitive configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: hetairos-config
  namespace: hetairos
data:
  ENVIRONMENT: "production"
  LOG_LEVEL: "info"
  DATABASE_NAME: "hetairos"
  QUEUE_NAME: "agent_tasks"
  MAX_WORKERS: "4"
  TIMEZONE: "UTC"

Apply:

kubectl apply -f configmap.yaml

API Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hetairos-api
  namespace: hetairos
  labels:
    app: hetairos
    component: api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hetairos
      component: api
  template:
    metadata:
      labels:
        app: hetairos
        component: api
    spec:
      containers:
      - name: api
        image: your-registry.azurecr.io/hetairos:latest
        imagePullPolicy: Always
        command: ["python", "src/main.py"]
        ports:
        - containerPort: 8000
          name: http
        env:
        - name: PORT
          value: "8000"
        envFrom:
        - configMapRef:
            name: hetairos-config
        - secretRef:
            name: hetairos-secrets
        resources:
          requests:
            memory: "2Gi"
            cpu: "500m"
          limits:
            memory: "4Gi"
            cpu: "1500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 5
      imagePullSecrets:
      - name: acr-secret

Worker Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hetairos-worker
  namespace: hetairos
  labels:
    app: hetairos
    component: worker
spec:
  replicas: 4
  selector:
    matchLabels:
      app: hetairos
      component: worker
  template:
    metadata:
      labels:
        app: hetairos
        component: worker
    spec:
      containers:
      - name: worker
        image: your-registry.azurecr.io/hetairos:latest
        imagePullPolicy: Always
        command: ["python", "run_workers.py"]
        envFrom:
        - configMapRef:
            name: hetairos-config
        - secretRef:
            name: hetairos-secrets
        resources:
          requests:
            memory: "2Gi"
            cpu: "500m"
          limits:
            memory: "4Gi"
            cpu: "1500m"
      imagePullSecrets:
      - name: acr-secret

Service

apiVersion: v1
kind: Service
metadata:
  name: hetairos-api
  namespace: hetairos
  labels:
    app: hetairos
    component: api
spec:
  type: ClusterIP
  ports:
  - port: 80
    targetPort: 8000
    protocol: TCP
    name: http
  selector:
    app: hetairos
    component: api

Ingress

Using NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hetairos-ingress
  namespace: hetairos
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  tls:
  - hosts:
    - hetairos.yourdomain.com
    secretName: hetairos-tls
  rules:
  - host: hetairos.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: hetairos-api
            port:
              number: 80

Using Azure Application Gateway

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hetairos-ingress
  namespace: hetairos
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  tls:
  - hosts:
    - hetairos.yourdomain.com
    secretName: hetairos-tls
  rules:
  - host: hetairos.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: hetairos-api
            port:
              number: 80

Horizontal Pod Autoscaler

API Autoscaler

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: hetairos-api-hpa
  namespace: hetairos
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: hetairos-api
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80

Worker Autoscaler

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: hetairos-worker-hpa
  namespace: hetairos
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: hetairos-worker
  minReplicas: 4
  maxReplicas: 20
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80

Deployment Commands

Initial Deployment

# Create namespace
kubectl apply -f k8s/namespace.yaml

# Create secrets and config
kubectl apply -f k8s/secrets.yaml
kubectl apply -f k8s/configmap.yaml

# Deploy application
kubectl apply -f k8s/api-deployment.yaml
kubectl apply -f k8s/worker-deployment.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/ingress.yaml

# Enable autoscaling
kubectl apply -f k8s/hpa.yaml

Verify Deployment

# Check pods
kubectl get pods -n hetairos

# Check services
kubectl get services -n hetairos

# Check ingress
kubectl get ingress -n hetairos

# View logs
kubectl logs -f deployment/hetairos-api -n hetairos
kubectl logs -f deployment/hetairos-worker -n hetairos

Rolling Updates

Update Image

# Build new image
docker build -t your-registry.azurecr.io/hetairos:v1.2.0 .
docker push your-registry.azurecr.io/hetairos:v1.2.0

# Update deployment
kubectl set image deployment/hetairos-api \
  api=your-registry.azurecr.io/hetairos:v1.2.0 \
  -n hetairos

kubectl set image deployment/hetairos-worker \
  worker=your-registry.azurecr.io/hetairos:v1.2.0 \
  -n hetairos

# Monitor rollout
kubectl rollout status deployment/hetairos-api -n hetairos
kubectl rollout status deployment/hetairos-worker -n hetairos

Rollback

# Rollback if issues
kubectl rollout undo deployment/hetairos-api -n hetairos
kubectl rollout undo deployment/hetairos-worker -n hetairos

Monitoring

Prometheus ServiceMonitor

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: hetairos-metrics
  namespace: hetairos
spec:
  selector:
    matchLabels:
      app: hetairos
      component: api
  endpoints:
  - port: http
    path: /metrics
    interval: 30s

Troubleshooting

Pod Not Starting

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

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

# Check logs
kubectl logs <pod-name> -n hetairos

Connection Issues

# Test service connectivity
kubectl run -it --rm debug --image=busybox --restart=Never -- sh
wget -O- http://hetairos-api.hetairos.svc.cluster.local

# Check endpoints
kubectl get endpoints -n hetairos

Resource Issues

# Check resource usage
kubectl top nodes
kubectl top pods -n hetairos

# Describe node
kubectl describe node <node-name>

Best Practices

Use resource limits - Prevent pods from consuming too many resources
Health checks - Implement liveness and readiness probes
Rolling updates - Zero-downtime deployments
Autoscaling - Handle variable load
Monitoring - Track metrics and logs
Security - Use RBAC, network policies, pod security policies
Secrets management - Use Key Vault or external secrets
Multiple environments - Separate dev, staging, production

Getting Started

Web Application

Integrations

Tools & Capabilities

Deployment

Kubernetes Deployment

Overview

Prerequisites

Architecture

Namespace

Secrets

Create Secret from Azure Key Vault

Or create secrets directly

ConfigMap

API Deployment

Worker Deployment

Service

Ingress

Using NGINX Ingress

Using Azure Application Gateway

Horizontal Pod Autoscaler

API Autoscaler

Worker Autoscaler

Deployment Commands

Initial Deployment

Verify Deployment

Rolling Updates

Update Image

Rollback

Monitoring

Prometheus ServiceMonitor

Troubleshooting

Pod Not Starting

Connection Issues

Resource Issues

Best Practices

Next Steps

Configuration Guide

Requirements

​Overview

​Prerequisites

​Architecture

​Namespace

​Secrets

​Create Secret from Azure Key Vault

​Or create secrets directly

​ConfigMap

​API Deployment

​Worker Deployment

​Service

​Ingress

​Using NGINX Ingress

​Using Azure Application Gateway

​Horizontal Pod Autoscaler

​API Autoscaler

​Worker Autoscaler

​Deployment Commands

​Initial Deployment

​Verify Deployment

​Rolling Updates

​Update Image

​Rollback

​Monitoring

​Prometheus ServiceMonitor

​Troubleshooting

​Pod Not Starting

​Connection Issues

​Resource Issues

​Best Practices

​Next Steps

Configuration Guide

Requirements

Overview

Prerequisites

Architecture

Namespace

Secrets

Create Secret from Azure Key Vault

Or create secrets directly

ConfigMap

API Deployment

Worker Deployment

Service

Ingress

Using NGINX Ingress

Using Azure Application Gateway

Horizontal Pod Autoscaler

API Autoscaler

Worker Autoscaler

Deployment Commands

Initial Deployment

Verify Deployment

Rolling Updates

Update Image

Rollback

Monitoring

Prometheus ServiceMonitor

Troubleshooting

Pod Not Starting

Connection Issues

Resource Issues

Best Practices

Next Steps