Skip to content
Docs menu

Helm chart for Kubernetes

Install Venom Cloud and the orchestrator on an existing Kubernetes cluster with one Helm chart, your own or a bundled Postgres, generated secrets, a pre-upgrade migration Job, ingress with TLS and optional NetworkPolicies.

View .md

deploy/helm/venom installs the whole stack on a cluster you already run (EKS, GKE, AKS, on-prem): the cloud workspace with its built-in scheduler, the orchestrator, and Postgres with pgvector, bundled or yours. It is a plain chart: no CRDs and no operator, the same stance as the kustomize manifests (ADR 0037), which stay for running the orchestrator alone. Nothing in it calls out except to what you configure.

Install

The images are the release's multi-arch ghcr.io/elishahbiz/venom-cloud and venom-orchestrator; the chart's appVersion is their default tag. From a checkout:

helm install venom deploy/helm/venom --namespace venom --create-namespace \
  --set ingress.enabled=true --set ingress.host=venom.example.com \
  --set ingress.className=nginx --set ingress.tls.enabled=true \
  --set ingress.tls.clusterIssuer=letsencrypt

Without values it installs with a bundled database and no ingress; reach it with the port-forward the install notes print. On the first visit the cloud shows /setup and asks for a one-time code, printed in its logs:

kubectl -n venom logs deploy/venom-venom-cloud | grep -i setup

Then follow Self-host Venom Cloud.

Database

Bundled (default) One pgvector/pgvector:pg17 StatefulSet with a PVC (database.bundled.storage, storageClass) and a generated password. Fine for a small install; it is not highly available and you back it up yourself.
Your own Postgres 15+ with the vector extension. Put the URL in a Secret and set database.external.existingSecret (key DATABASE_URL, or urlKey); unpooledUrlKey is optional for a pooled primary URL. The bundled database is then not rendered.
kubectl -n venom create secret generic venom-db \
  --from-literal=DATABASE_URL='postgres://venom:…@db.internal:5432/venom_cloud?sslmode=require'
helm install venom deploy/helm/venom -n venom --set database.external.existingSecret=venom-db

Secrets

By default the chart generates, once, the same set scripts/cloud-env.sh makes: VENOM_CLOUD_ADMIN_TOKEN, VENOM_VAULT_KEYS, VENOM_MESH_SIGNING_KEYS, VENOM_POLICY_SIGNING_KEY, CRON_SECRET, AUTH_SECRET, plus the orchestrator's VENOM_API_KEY and VENOM_ADMIN_TOKEN and the database password. An upgrade reads the existing Secrets with Helm's lookup and keeps every value. The Secrets carry helm.sh/resource-policy: keep, so helm uninstall leaves them: VENOM_VAULT_KEYS opens everything the vault sealed, so back the cloud Secret up.

lookup only sees a cluster when Helm talks to one. helm template | kubectl apply and GitOps tools that render offline (Argo CD, Flux with helm template) would regenerate the values on each sync. In those setups create the Secrets yourself and name them: secrets.existingSecret (the six cloud keys) and orchestrator.existingSecret (VENOM_API_KEY, VENOM_ADMIN_TOKEN). Provider keys go in the optional Secret venom-provider-keys (orchestrator.providerKeysSecret), each key an environment variable.

Upgrade, migrations and rollback

Set a new image.cloud.tag (or upgrade to a chart version whose appVersion is newer) and run helm upgrade. Before the pods roll, a pre-upgrade Job runs node scripts/migrate.ts against the database. If a migration fails, Helm stops and the old pods keep serving. The image also migrates on start under a Postgres advisory lock, which covers the first install (the Job is not a pre-install hook, because a bundled database does not exist yet) and makes it safe for several replicas to start together.

Migrations are expand/contract (ADR 0074): the image N-1 runs on schema N. That is why helm rollback venom (an image swap) is safe after an upgrade; a release that contracts the schema names the version you must pass through first, so do not skip releases. Take a database backup before a major jump.

The chart does not update itself. The signed update check in the compose installs belongs to that installer; on Kubernetes, helm upgrade is the update and nothing contacts the internet unless you ask.

Exposing it, and the network

ingress.enabled renders an Ingress to the cloud Service (ingress.host is required, className as your controller expects). With ingress.tls.enabled the host is served from ingress.tls.secretName (your own kubernetes.io/tls Secret, or the name cert-manager fills in); ingress.tls.clusterIssuer adds the cert-manager annotation. VENOM_CLOUD_ORIGIN follows the host (cloud.origin overrides). The orchestrator is a ClusterIP Service, reached by the cloud and by workloads in the cluster; its admin API shares the port, so expose /v1 only if you expose it.

networkPolicy.enabled (needs a CNI that enforces them) limits the cloud to ingress from networkPolicy.ingressFrom (point it at your ingress controller's namespace) and egress to DNS, the database, the orchestrator and networkPolicy.egress.to on egress.ports (default: HTTPS anywhere, for model providers and OAuth). Narrow that to your providers' addresses to be strict. The bundled database accepts connections from the cloud pods and the migration Job only. With an external database set egress.databaseCIDR.

What gets created

Cloud A Deployment (cloud.replicas, default 1; more are safe because the scheduler dedupes duties through the cron_runs table, so each Deployment pod runs the same cron runner and a duty runs once), a Service, a ServiceAccount and, from two replicas, a PodDisruptionBudget (minAvailable: 1).
Orchestrator One replica with Recreate on a ReadWriteOnce PVC (SQLite), its Service, and a ConfigMap of config/orchestrator.yaml and prices.yaml (or your orchestrator.existingConfigMap). orchestrator.enabled=false leaves it out.
Postgres The StatefulSet and headless Service, unless database.external is set.
Hardening Every pod runs non-root with a read-only root filesystem (writable /tmp and data volumes only), all capabilities dropped, RuntimeDefault seccomp, no service account token, resource requests on every container, and startup, liveness and readiness probes.

Publishing

Publishing the chart to an OCI registry with each release, signed, is a release workflow step that is added separately. Until then install from the checkout as above, or helm package deploy/helm/venom and helm push it to a registry you run.