Source: docs/manual/kubernetes-deployment.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Kubernetes Deployment Guide

Prerequisites

• Kubernetes 1.28+
• Helm 3.14+
• kubectl configured for the target cluster
• Access to ghcr.io/cruvero/*
• Vault Secrets Operator (optional, for Vault-backed secrets)
• Argo CD 2.10+ (optional, for GitOps)
• Prometheus Operator (optional, for ServiceMonitor discovery)

Quick Start (Dev)

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add qdrant https://qdrant.github.io/qdrant-helm
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm repo update

helm dependency build charts/cruvero

helm install cruvero charts/cruvero \
  -f charts/cruvero/values-dev.yaml \
  --namespace cruvero-dev \
  --create-namespace

Building Container Images

CI image builds are defined in .github/workflows/build-images.yaml.

Manual example:

docker build -f docker/Dockerfile.worker -t ghcr.io/cruvero/worker:dev .
docker push ghcr.io/cruvero/worker:dev

Chart Configuration

Key value groups in charts/cruvero/values.yaml:

• Service blocks (worker, api, ui, graphWorker, embedWorker) for replicas, resources, and HPA
• env map for CRUVERO_* runtime configuration
• Infrastructure dependencies (postgresql, qdrant, nats as subcharts; dragonflydb as native template)
• vault for Vault secret sync configuration
• ingress for external routing/TLS
• monitoring for ServiceMonitor generation
• secrets for non-Vault runtime secret source (existingSecret or chart-managed secret data)

Vault Setup

The chart follows the Vault Secrets Operator pattern:

• vault.enabled=true renders VaultStaticSecret
• vault.authRef points at an existing VaultAuth in the same namespace (recommended)
• optionally set vault.createAuth=true to have the chart create VaultAuth

vault kv put secret/cruvero \
  CRUVERO_POSTGRES_URL="postgres://..." \
  CRUVERO_OPENAI_CHAT_API_KEY="sk-..." \
  CRUVERO_EMBEDDING_API_KEY="sk-..." \
  CRUVERO_PII_HMAC_KEY="..."

helm install cruvero charts/cruvero \
  -f charts/cruvero/values-staging.yaml \
  --set vault.enabled=true \
  --set vault.authRef=default

If Vault is disabled, provide a Kubernetes Secret source explicitly:

kubectl create secret generic cruvero-dev-secrets -n cruvero-dev \
  --from-literal=CRUVERO_POSTGRES_URL='postgres://...'

helm install cruvero charts/cruvero \
  -f charts/cruvero/values-dev.yaml \
  --set vault.enabled=false \
  --set secrets.existingSecret=cruvero-dev-secrets

Argo CD Setup (GitOps)

kubectl apply -f deploy/argocd/project.yaml
kubectl apply -f deploy/argocd/applicationset.yaml

argocd app list | grep cruvero

• dev tracks branch dev with auto-sync
• staging tracks main with auto-sync
• prod tracks main with manual sync (no auto-sync)

Monitoring

helm upgrade cruvero charts/cruvero \
  --namespace cruvero-dev \
  --set monitoring.enabled=true

kubectl get servicemonitors -n cruvero-dev

Scaling and HA

Use Helm values for replica counts and HPA ranges:

• worker.replicaCount, api.replicaCount, etc.
• worker.hpa.* and api.hpa.*
• Topology spread constraints are enabled automatically when replicas are > 1
• PDBs are generated automatically for services with replicas > 1

Probe/port defaults are service-specific:

• worker: probe server :8082 with /healthz and /readyz
• api: port 8900 with /v1/health and /v1/health/ready
• ui: port 8080 with /api/health
• graph-worker and embed-worker: probes disabled by default (no HTTP probe server)

For detailed HA guidance, see docs/operations/ha-deployment.md.

Troubleshooting

• Migration hook failures:

kubectl logs job/<release>-cruvero-migrate -n cruvero-dev

• Service startup failures:

kubectl get configmap,secret -n cruvero-dev | grep cruvero

• Health check failures:

kubectl describe pod <pod-name> -n cruvero-dev

• Vault sync failures:

kubectl get vaultstaticsecret -n cruvero-dev
kubectl describe vaultstaticsecret <name> -n cruvero-dev

For bare-metal/non-Kubernetes deployment details, see docs/manual/debian-deploy.md.