Skip to main content

​
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

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

​
Next Steps

Configuration Guide

Configure Praxos settings

Requirements

Review deployment requirements