Kubernetes Deployment

This guide covers deploying Corbulo on Kubernetes for production environments that need scaling, high availability, and operational maturity. This is the recommended approach for teams with 50+ developers or when uptime requirements are critical.

Prerequisites

Kubernetes 1.28+
Helm 3.x
kubectl configured for your cluster
PostgreSQL 16+ (managed or self-hosted)
Redis 7+ (managed or self-hosted)
FalkorDB instance
Temporal server
A registered GitHub App (see GitHub Integration)
A Clerk account for authentication
Access to an OpenAI-compatible AI model API

For production deployments, use managed database services (e.g., Amazon RDS, Cloud SQL, Azure Database) rather than running PostgreSQL and Redis inside the cluster.

Quick Start

Add the Corbulo Helm repository

helm repo add corbulo https://charts.corbulo.dev
helm repo update

Create a namespace

kubectl create namespace corbulo

Create secrets

Store sensitive configuration in Kubernetes secrets:

kubectl create secret generic corbulo-config \
  --namespace corbulo \
  --from-literal=DATABASE_URL='postgres://user:pass@host:5432/corbulo?sslmode=require' \
  --from-literal=REDIS_URL='redis://host:6379' \
  --from-literal=SECRET_KEY='your-secret-key' \
  --from-literal=CLERK_SECRET_KEY='your-clerk-secret' \
  --from-literal=GITHUB_WEBHOOK_SECRET='your-webhook-secret' \
  --from-literal=LLM_OPENAI_LARGE_API_KEY='your-api-key' \
  --from-literal=LLM_OPENAI_SMALL_API_KEY='your-api-key'

kubectl create secret generic github-private-key \
  --namespace corbulo \
  --from-file=github-app.pem=/path/to/your/private-key.pem

Create a values file

Create values.yaml with your configuration. See the values reference below.

Install the chart

helm install corbulo corbulo/corbulo \
  --namespace corbulo \
  --values values.yaml

Run database migrations

kubectl exec -n corbulo deploy/corbulo-api -- corbulo migrate up

Verify the deployment

kubectl exec -n corbulo deploy/corbulo-api -- curl -s http://localhost:8080/healthz

values.yaml Reference

# Corbulo Helm chart values

global:
  image:
    repository: ghcr.io/corbulo/corbulo-api
    tag: latest
    pullPolicy: Always

# API Server
api:
  replicas: 2
  port: 8080
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: 2000m
      memory: 2Gi
  env:
    APP_ENV: production
    LOG_LEVEL: info
    TEMPORAL_ADDRESS: temporal.temporal:7233
    FALKORDB_HOST: falkordb.corbulo:6379
    CLERK_JWT_ISSUER: https://your-clerk-instance.clerk.accounts.dev
    GITHUB_APP_ID: "123456"
    GITHUB_PRIVATE_KEY_PATH: /keys/github-app.pem
    FRONTEND_URL: https://corbulo.yourcompany.com
    BACKEND_URL: https://api.corbulo.yourcompany.com
    CORS_ORIGINS: https://corbulo.yourcompany.com
    LLM_OPENAI_LARGE_PROVIDER: openai
    LLM_OPENAI_LARGE_MODEL: gpt-4o
    LLM_OPENAI_LARGE_BASE_URL: https://api.openai.com/v1
    LLM_OPENAI_SMALL_PROVIDER: openai
    LLM_OPENAI_SMALL_MODEL: gpt-4o-mini
    LLM_OPENAI_SMALL_BASE_URL: https://api.openai.com/v1
  envFromSecret: corbulo-config
  volumeMounts:
    - name: github-key
      mountPath: /keys
      readOnly: true
  volumes:
    - name: github-key
      secret:
        secretName: github-private-key
  service:
    type: ClusterIP
    port: 8080
  ingress:
    enabled: true
    className: nginx
    hosts:
      - host: api.corbulo.yourcompany.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: corbulo-api-tls
        hosts:
          - api.corbulo.yourcompany.com

# Analysis Workers
worker:
  replicas: 2
  resources:
    requests:
      cpu: 1000m
      memory: 1Gi
    limits:
      cpu: 4000m
      memory: 4Gi
  env:
    AGENT_EXECUTION_MODE: k8s
    K8S_AGENT_NAMESPACE: corbulo
  envFromSecret: corbulo-config
  volumeMounts:
    - name: github-key
      mountPath: /keys
      readOnly: true
  volumes:
    - name: github-key
      secret:
        secretName: github-private-key

# Frontend
frontend:
  replicas: 2
  image:
    repository: ghcr.io/corbulo/corbulo-frontend
    tag: latest
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 256Mi
  service:
    type: ClusterIP
    port: 80
  ingress:
    enabled: true
    className: nginx
    hosts:
      - host: corbulo.yourcompany.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: corbulo-frontend-tls
        hosts:
          - corbulo.yourcompany.com

# Monitoring
metrics:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: 30s
    path: /metrics
    port: 8080

Scaling

Horizontal Scaling

The API server and workers scale independently. Workers are the primary scaling target — add more replicas to process analysis tasks faster.

# Scale workers for higher analysis throughput
kubectl scale deploy corbulo-worker -n corbulo --replicas=5

# Scale API for higher request throughput
kubectl scale deploy corbulo-api -n corbulo --replicas=4

Horizontal Pod Autoscaler

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

Resource Sizing Guide

Team Size	API Replicas	Worker Replicas	Worker CPU	Worker Memory
10-50 devs	2	2	1000m	1 Gi
50-200 devs	3	4	2000m	2 Gi
200+ devs	4+	6+	2000m	4 Gi

High Availability

API Server

Run at least 2 replicas with pod anti-affinity to spread across nodes:

api:
  replicas: 2
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchLabels:
                app: corbulo-api
            topologyKey: kubernetes.io/hostname

Workers

Workers are stateless and can tolerate pod restarts. Temporal automatically retries tasks assigned to workers that go down. Run at least 2 replicas in production.

Infrastructure Services

For high availability of infrastructure services:

PostgreSQL: Use a managed service with automated failover (Amazon RDS, Cloud SQL, Azure Database).
Redis: Use a managed service with replication (ElastiCache, Memorystore, Azure Cache).
Temporal: Deploy the Temporal server cluster with multiple history and matching service replicas.
FalkorDB: Run with persistent storage and regular backups.

Operations

Health Checks

The Helm chart configures liveness and readiness probes automatically. The health endpoints are:

Endpoint	Purpose
`/healthz`	Simple health check. Returns 200 if the service is running. Used for liveness probes.
`/health/detailed`	Component health check. Returns status of each infrastructure dependency with circuit breaker state. Used for readiness probes.

Monitoring

Corbulo exposes Prometheus metrics at /metrics on port 8080. The Helm chart can create a ServiceMonitor for automatic Prometheus discovery. Key metrics to monitor:

HTTP request latency and error rates
Active Temporal workflow counts
Analysis task duration and failure rates
Database connection pool utilization

OpenTelemetry tracing is supported via standard OTEL_* environment variables. Enable it in your values:

api:
  env:
    OTEL_ENABLED: "true"
    OTEL_ENDPOINT: "otel-collector.monitoring:4317"

Logs

All components write structured JSON logs to stdout. Use your cluster’s log aggregation pipeline (Fluentd, Loki, CloudWatch Logs, etc.) to collect and search logs.

# View API logs
kubectl logs -n corbulo -l app=corbulo-api -f

# View worker logs
kubectl logs -n corbulo -l app=corbulo-worker -f

Upgrades

# Update Helm repository
helm repo update

# Upgrade to latest version
helm upgrade corbulo corbulo/corbulo \
  --namespace corbulo \
  --values values.yaml

# Run any new migrations after upgrade
kubectl exec -n corbulo deploy/corbulo-api -- corbulo migrate up

Backups

Back up the PostgreSQL database regularly using your managed service’s backup features or pg_dump. Redis and FalkorDB contain derived data that can be reconstructed from a fresh analysis run.

Troubleshooting

Pods stuck in CrashLoopBackOff

Check the pod logs for the specific error:

kubectl logs -n corbulo deploy/corbulo-api --previous

The most common causes are missing environment variables (the application logs which variable is unset) or unreachable infrastructure services.

Readiness probe failing

The readiness probe calls /health/detailed, which checks connectivity to all infrastructure services. Identify which component is unhealthy:

kubectl exec -n corbulo deploy/corbulo-api -- curl -s http://localhost:8080/health/detailed | jq .

The response includes the status of each dependency (PostgreSQL, Redis, FalkorDB, Temporal).

Workers not picking up tasks

Verify workers are connected to Temporal and the correct namespace:

kubectl logs -n corbulo -l app=corbulo-worker --tail=50

Confirm that TEMPORAL_ADDRESS and TEMPORAL_NAMESPACE match between the API and worker deployments.

Ingress not routing traffic

Verify the ingress resource is created and has an address assigned:

kubectl get ingress -n corbulo

Confirm your DNS records point to the ingress controller’s external IP or load balancer. Check the ingress controller logs if requests are not reaching the Corbulo pods.

Analysis tasks timing out

Analysis task duration depends on repository size and AI model response time. If tasks are timing out:

Check AI model API latency — slow responses from the model provider are the most common cause.
Scale workers to reduce queue depth.
Verify workers have sufficient memory — large repositories require more memory during analysis.

Getting Started

Core Features

Configuration

Integrations

Self-Hosting

Kubernetes Deployment

Kubernetes Deployment

Prerequisites

Quick Start

values.yaml Reference

Scaling

Horizontal Scaling

Horizontal Pod Autoscaler

Resource Sizing Guide

High Availability

API Server

Workers

Infrastructure Services

Operations

Health Checks

Monitoring

Logs

Upgrades

Backups

Troubleshooting

​Kubernetes Deployment

​Prerequisites

​Quick Start

​values.yaml Reference

​Scaling

​Horizontal Scaling

​Horizontal Pod Autoscaler

​Resource Sizing Guide

​High Availability

​API Server

​Workers

​Infrastructure Services

​Operations

​Health Checks

​Monitoring

​Logs

​Upgrades

​Backups

​Troubleshooting

Kubernetes Deployment

Prerequisites

Quick Start

values.yaml Reference

Scaling

Horizontal Scaling

Horizontal Pod Autoscaler

Resource Sizing Guide

High Availability

API Server

Workers

Infrastructure Services

Operations

Health Checks

Monitoring

Logs

Upgrades

Backups

Troubleshooting