AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
icon: ⛵
Helm Chart
The Kubernetes install we ship to self-hosters, at deploy/activepieces-helm/. It is the Kubernetes peer of the docker-compose.yml on the Docker page — same app, different orchestrator — and it is not how our own Cloud deploys (see Cloud Deployment Paths, which runs Kamal and k3s).
Two paths for an AP_* variable
templates/deployment.yaml builds one env: list from two values keys, in this fixed order:
activepiecesConfig— a flat map rendered as plainvalue:entries. Rendered first. Empty ({}) by default.activepiecesEnvVariables— a map of secret name → list of var names, rendered assecretKeyRefwithoptional: true. Rendered second. The shipped default routesAP_EDITION,AP_EXECUTION_MODE,AP_ENCRYPTION_KEY,AP_JWT_SECRETand the queue/auth vars through secrets the chart does not create.envFromthe generated secrets: lowest precedence. SuppliesAP_ENCRYPTION_KEY/AP_JWT_SECRETwhen no user secret sets them, becauseenvbeatsenvFrom.
What the chart creates
Only two secrets, both data: {} with mittwald secret-generator annotations that fill them in-cluster: <release>-secrets (AP_ENCRYPTION_KEY) and <release>-jwt-secret (AP_JWT_SECRET). Postgres and Redis come from the Bitnami subcharts (off by default, images from bitnamilegacy/*). With workloadType unset, the activepieces.workloadType helper picks a StatefulSet only on a live cluster (kind-level entries like apps/v1/StatefulSet in .Capabilities.APIVersions) that has no Argo Rollouts and no <fullname>-preview Service from an earlier Rollout revision; everything else, including offline renders, stays a Rollout as on main.
Key files
deploy/activepieces-helm— chart,values.yaml, andtemplates/
Gotchas
- Setting the same
AP_*var in both values keys puts two entries with one name in the pod spec, and the secret wins.activepiecesConfigrenders beforeactivepiecesEnvVariables, and for duplicate env names the later entry is what the container process sees. Since the shippedvalues.yamlalready listsAP_EDITIONandAP_EXECUTION_MODEunderactivepieces-config-secrets, a user who follows the docs and has created that secret silently gets the secret's edition, not the one they set.optional: truesaves the common case — with no such secret the ref is skipped and the plain value survives — so this reads as "works on my cluster" right up until someone populates the secret. Set each variable in exactly one place. - The DB and Redis secrets do not exist until you make them. Every ref is
optional: true, so a missing secret is silently skipped and the app falls back to its own defaults (e.g.localhostPostgres), even with the subcharts enabled. - Offline renders can't see the cluster. Helm's default
.Capabilities.APIVersionshas group/version entries only; a connected install adds kind-level ones such asapps/v1/StatefulSet. That is the only live-cluster signal that works with--create-namespaceand restricted RBAC (alookupsees no namespace yet and errors on Forbidden). - Releases born on chart 0.3.x keep their key under legacy field names. Their
<fullname>-secretsholdsencryption-key(and<fullname>-jwt-secretholdsjwt-secret), while the generator now writesAP_ENCRYPTION_KEY. When no user secret pins the key, the chart looks up the legacy field and pins it, so the upgrade keeps decrypting old data. Offline renders cannot look it up; the migration guide copies it intoactivepieces-auth-secretsinstead. - Never render an empty
AP_CONTAINER_TYPE. Current images treat empty and unset alike (${AP_CONTAINER_TYPE:-WORKER_AND_APP}), but pre-worker-v2 images start as a worker when it is set to"", so every API route returns 404. - A StatefulSet's volume template is frozen once created. A 0.3.x user who upgrades with old values gets a StatefulSet on
local-path; fixingpersistence.storageClassNameafterwards is rejected until the StatefulSet and its cache PVC are deleted (safe while the pod never started). - Chart 0.3.x only ran bundled Postgres when the release name contained
activepieces. It referenced<fullname>-postgresqlwhile Bitnami names the secret<release>-postgresql. - A user-owned key is pinned once it exists. If
AP_ENCRYPTION_KEY/AP_JWT_SECRETare in the user's secret when the chart renders, theirsecretKeyRefbecomesoptional: false, so a deleted secret stops the pod instead of letting the generated fallback key silently take over. - Never render one env name twice to get precedence. Helm 4 installs with server-side apply, which rejects duplicate
envkeys ("duplicate entries for key"). A lower-precedence default has to come throughenvFrom. - Removing a duplicate env name on a Helm 3 upgrade deletes both entries. The strategic merge patch matches
envitems by name ("hides previous definition ... may be dropped when using apply"), so a var set in both values keys vanishes from the live pod spec. Never change how an already-duplicated name renders; fix duplicates in the user's values instead. - Up to 0.92.x,
AP_FRONTEND_URLmust be reachable from inside the pod. Those releases download piece bundles through the public URL, so alocalhostvalue boots fine and then fails every flow withfetch failed. Later releases download over the worker's own app URL (127.0.0.1in the chart's single container), see the bundle-download gotcha on Workers. - The mittwald subchart's ClusterRole is named after the release. Two releases with the same name in different namespaces collide, and deleting a namespace without
helm uninstallleaves it behind. A second release can setkubernetes-secret-generator.enabled: false; the first operator watches every namespace. - Helm 4 upgrades of a
Rolloutneed--force-conflicts. Argo's controller owns the Service.spec.selector(it addsrollouts-pod-template-hash), so server-side apply conflicts. After a forced upgrade Argo re-adds the hash and traffic keeps routing. - The HPA targets whatever
activepieces.workloadTyperesolves to. It used to target aDeploymentthe chart never creates. Chart.yamlappVersionis the default image tag.release-self-hosted.ymlfails the release if it drifts frompackage.json, and the version sync PR bumps it.AP_EDITION=eeneedsAP_EXECUTION_MODEset in the same breath or the pod will not boot.system-validator.tsthrows forcloud/eein production unless the mode is one ofSANDBOX_PROCESS,SANDBOX_CODE_ONLY,SANDBOX_CODE_AND_PROCESS, and the default isUNSANDBOXED. The error names the execution mode, not the edition, so it reads as a sandboxing problem rather than the edition switch that caused it.- Health checks need the
/apiprefix. On a production app pod,setNotFoundHandleranswers any non-/api/path without a file extension with the SPAindex.htmland a 200. So a probe orhelm teston/v1/healthor/passes as soon as the server listens and never reaches the database check behind/api/v1/health(503 when Postgres is unreachable). - Bumping the bundled Bitnami subcharts is a database migration, not a version bump.
postgresqlpast 11.7.2 ships PostgreSQL 17, which will not start on the 14 data directory, so every bundled-DB install needs a dump, a freshdata-<release>-postgresql-0claim and a restore while the app is held at zero replicas (and HPA off). Plan it as its own release with migration docs. Images only exist underbitnamilegacy/*since Bitnami's 2025-08-28 freeze; check a target chart's default tags exist there first. See GIT-1929. - OpenShift support is an overlay, not a default.
values-openshift.yamlmoves the pod to non-root on 8080 without capabilities and turns off the bundled subcharts' security contexts (they hardcode user ID 1001); the base chart stays root on port 80 soSANDBOX_PROCESSinstalls keep working. The overlay must never setrunAsUser/fsGroup(restricted-v2 rejects IDs outside the project's range) orAP_EXECUTION_MODE(the shipped values already read it from a secret, so it would render twice). See GIT-1929. - An empty
persistence.storageClassNamekeeps whatever class the live StatefulSet already has. A StatefulSet'svolumeClaimTemplatesare immutable, so any change there fails the wholehelm upgrade("updates to statefulset spec ... are forbidden").activepieces.cacheStorageClassNamelooks the old class up and reuses it; offline renders (Argo CD,helm template) cannot, so changing the chart's default class is a breaking change for them even thoughhelm upgradesurvives it. - A failed
helm upgradeis not atomic. Resources Helm patched before the failing one stay patched, so a release can end up half on the new chart, for example a bundled database already on a new major image while the app StatefulSet patch was rejected. Run anything irreversible (dumps, backups) before the upgrade, not after it fails.