---
title: Helm chart for Kubernetes
description: 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.
section: deploy
order: 41
audience: [operator]
sources: [deploy/helm/venom, scripts/test-helm.sh, docs/kubernetes.md, docs/adr/0037-kubernetes-manifests.md, docs/adr/0074-selfhost-updates.md]
features: [deploy.kubernetes]
---

`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](/docs/deploy/kubernetes.md) (ADR 0037), which stay for running the orchestrator alone. Nothing in it calls out except to what you configure.

## Install {#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:

```bash
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:

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

Then follow [Self-host Venom Cloud](/docs/deploy/self-host-cloud.md#first-visit-the-setup-screen).

## Database {#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. |

```bash
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 {#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 {#upgrade}

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](/docs/deploy/updates)): 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](/docs/deploy/updates.md) 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}

`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 {#objects}

| | |
|---|---|
| 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}

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.

## Related

- [Kubernetes (orchestrator alone)](/docs/deploy/kubernetes.md)
- [Self-host Venom Cloud](/docs/deploy/self-host-cloud.md)
- [Update a self-hosted Venom Cloud](/docs/deploy/updates.md)
