Overview
z3rno-helm is the Helm chart that runs Z3rno on Kubernetes. The base chart renders four workload kinds:
| Workload | Default | Notes |
|---|
Deployment/z3rno-server | 2 replicas | The FastAPI application. |
Deployment/z3rno-worker | 1 replica | Celery worker. |
Deployment/z3rno-beat | 1 replica | Celery beat scheduler. Singleton — do not scale beyond 1. |
StatefulSet/z3rno-valkey | 1 replica | Bundled Valkey (Celery broker + rate-limit store). |
enabled: false by default and back-compat — pre-flag deploys stay byte-identical.
| Opt-in | Flag | Adds | Shipped |
|---|
| Bundled Postgres (CNPG subchart) | z3rno-postgres.enabled | A postgresql.cnpg.io/v1 Cluster CR running the z3rno-postgres:17 image (Postgres 17 + pgvector + AGE + pg_cron + pgaudit + pgcrypto). | v0.19.7 |
| Observability (Prometheus + Grafana) | observability.prometheusRules.enabled / observability.grafanaDashboard.enabled | 4 SLO recording rules + 4 alerts + a stat/timeseries dashboard. | v0.18.0 |
| Multi-region topology | multiRegion.enabled | z3rno.region label, zonal topologySpreadConstraints, optional DATABASE_READ_URL in the secret. | v0.17.0 |
| Inline image-pull secret | imagePullSecret.create | Renders a dockerconfigjson Secret for private GHCR. | v0.19.10 |
| NOTIFY/LISTEN audit drain | auditListener.enabled | A dedicated singleton Deployment/z3rno-audit-listener that opens LISTEN z3rno_audit_pending and fires z3rno.audit_drain on every notification. | v0.20.2 |
0.6.0 (appVersion 0.20.0).
Install
The chart currently ships from source; an OCI / repo publish lands in a future release.
git clone https://github.com/the-ai-project-co/z3rno-helm
cd z3rno-helm
helm install z3rno ./charts/z3rno \
--namespace z3rno --create-namespace \
--set externalDatabase.enabled=true \
--set externalDatabase.host=YOUR_DB_HOST \
--set secrets.databaseUrl='postgresql+asyncpg://z3rno:PASSWORD@YOUR_DB_HOST:5432/z3rno' \
--set secrets.openaiApiKey=sk-your-openai-key
kind) with bundled Postgres, see the Self-hosting / Kubernetes guide.
Quick start (production shape)
helm install z3rno ./charts/z3rno -n z3rno --create-namespace -f values-production.yaml
values-production.yaml:
server:
image:
repository: ghcr.io/safayavatsal/z3rno-server # public mirror; OK for prod
tag: "0.20.0"
replicas: 3
externalDatabase:
enabled: true
host: "z3rno-db.abc123.us-east-1.rds.amazonaws.com"
existingSecret: "z3rno-db-credentials" # must have key 'password'
secrets:
databaseUrl: "postgresql+asyncpg://z3rno:PASSWORD@z3rno-db.abc123...:5432/z3rno"
openaiApiKey: "sk-..."
z3rnoApiKey: "z3rno_sk_prod_..." # rotate from the dev default
ingress:
enabled: true
className: nginx
hosts:
- host: api.example.com
paths:
- path: /
pathType: Prefix
autoscaling:
enabled: true
minReplicas: 2
maxReplicas: 10
targetCPUUtilizationPercentage: 70
# Recommended pairing: live audit drain via NOTIFY/LISTEN
auditListener:
enabled: true
beat:
audit:
drainIntervalSeconds: "60.0" # bump up; listener handles wake-up
values.yaml reference
The full reference shape, organized by block:
# Server
server:
image:
repository: ghcr.io/safayavatsal/z3rno-server # public mirror default
tag: latest
pullPolicy: IfNotPresent
replicas: 2
port: 8000
resources:
requests: { memory: 256Mi, cpu: 250m }
limits: { memory: 512Mi, cpu: 500m }
# Celery worker
worker:
enabled: true
replicas: 1
command: "celery -A z3rno_server.workers.celery_app worker --loglevel=info"
# Celery beat (singleton)
beat:
enabled: true
replicas: 1
command: "celery -A z3rno_server.workers.celery_app beat --loglevel=info"
audit:
drainIntervalSeconds: "1.0" # bump to 60.0 when auditListener.enabled
drainBatchSize: "500"
maxOrgsPerTick: "100"
# Bundled Valkey
valkey:
enabled: true # set false + use externalRedis for prod
image: { repository: valkey/valkey, tag: "8" }
port: 6379
persistence:
enabled: true
size: 1Gi
storageClass: ""
# External Postgres (recommended for prod)
externalDatabase:
enabled: false
host: ""
port: 5432
name: "z3rno"
user: "z3rno"
existingSecret: ""
secretKey: "password"
# External Redis (replaces bundled Valkey)
externalRedis:
enabled: false
host: ""
port: 6379
existingSecret: ""
secretKey: "redis-password"
# Secrets — set existingSecret to source from your secret manager
secrets:
databaseUrl: ""
redisUrl: ""
openaiApiKey: ""
z3rnoApiKey: "z3rno_sk_test_localdev" # rotate for non-localhost deploys
existingSecret: ""
# Ingress
ingress:
enabled: false
className: ""
annotations: {}
hosts:
- host: z3rno.local
paths: [{ path: /, pathType: Prefix }]
tls: []
# Horizontal Pod Autoscaler (targets server)
autoscaling:
enabled: false
minReplicas: 2
maxReplicas: 10
targetCPUUtilizationPercentage: 70
targetMemoryUtilizationPercentage: 80
# Pod Disruption Budget (targets server)
podDisruptionBudget:
enabled: false
minAvailable: 1
# Free-form env injected into server / worker / beat pods
env: {}
Opt-in blocks
# v0.19.7 — bundled Postgres via CloudNativePG subchart.
# When true, renders a postgresql.cnpg.io/v1 Cluster CR running
# z3rno-postgres:17 (Postgres 17 + pgvector + AGE + pg_cron +
# pgaudit + pgcrypto). Auto-emits <release>-z3rno-rw / -ro services.
# Requires the CNPG operator pre-installed in the cluster.
z3rno-postgres:
enabled: false
# v0.18.0 — Prometheus rules + Grafana dashboard.
observability:
prometheusRules:
enabled: false # needs prometheus-operator CR
extraLabels: {}
grafanaDashboard:
enabled: false # needs Grafana sidecar
extraLabels: {}
# v0.17.0 — multi-region topology.
multiRegion:
enabled: false
region: "" # e.g. "us-east-1"
zones: [] # zonal topology spread
readDatabaseUrl: "" # populates DATABASE_READ_URL
secondaryRegions: [] # documentation field
# v0.19.10 — inline ghcr.io pull secret (alt: pre-create + use imagePullSecrets).
imagePullSecret:
create: false
registry: "ghcr.io"
username: ""
password: "" # GH PAT with read:packages
dockerconfigjson: "" # OR pre-built base64 dockerconfigjson
# v0.20.2 — NOTIFY/LISTEN audit drain listener.
# When true, deploys a singleton z3rno-audit-listener pod that opens
# LISTEN z3rno_audit_pending and fires z3rno.audit_drain on every
# notification (~50 ms wake instead of waiting for beat). The beat-
# driven poll stays as a fallback; bump beat.audit.drainIntervalSeconds
# to 60.0 when listener is enabled.
auditListener:
enabled: false
Using an external database
For production, point at a managed PostgreSQL (RDS, Cloud SQL, Neon, or self-managed):
externalDatabase:
enabled: true
host: "z3rno-db.abc123.us-east-1.rds.amazonaws.com"
port: 5432
name: "z3rno"
user: "z3rno"
existingSecret: "z3rno-db-credentials" # must contain key 'password'
Your external PostgreSQL must have pgvector, Apache AGE, pg_cron, pgaudit, and pgcrypto installed. The reference image ghcr.io/the-ai-project-co/z3rno-postgres:17 ships all five pre-compiled — use it directly if you can, or replicate the extension set on your managed instance. The z3rno-postgres subchart (set z3rno-postgres.enabled=true) renders a CNPG-managed cluster of this image for you.
Upgrading
git pull # in the z3rno-helm checkout
helm upgrade z3rno ./charts/z3rno -n z3rno -f values.yaml
alembic upgrade head against the configured DATABASE_URL. Pre-flight check:
kubectl get pods -n z3rno
kubectl logs -n z3rno -l app.kubernetes.io/component=server -c migrate
Uninstalling
helm uninstall z3rno --namespace z3rno
# PVCs are retained — manually delete to wipe Valkey + (if bundled) Postgres data
kubectl delete pvc -l app.kubernetes.io/instance=z3rno -n z3rno
Resource recommendations
| Scale | Server CPU/mem | Worker CPU/mem | Postgres CPU/mem | Postgres storage |
|---|
| Dev / test | 250m / 512Mi | 250m / 256Mi | 500m / 1Gi | 10Gi |
| Small (< 100K memories) | 500m / 1Gi | 500m / 512Mi | 1 / 2Gi | 50Gi |
| Medium (< 1M memories) | 1 / 2Gi | 1 / 1Gi | 2 / 8Gi | 200Gi |
| Large (> 1M memories) | 2 / 4Gi | 2 / 2Gi | 4 / 16Gi+ | 500Gi+ |
status/PHASE-3-DEFERRED-TESTS.md in z3rno-process-docs.
Reference
