Skip to content

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

fix(helm): the Helm chart installs and starts with its documented setup (#15774)

Hazem Adeld0dbb5083f71
diff --git a/.github/workflows/helm-chart.yml b/.github/workflows/helm-chart.yml
new file mode 100644
index 00000000000..e2a2ba7627a
--- /dev/null
+++ b/.github/workflows/helm-chart.yml
@@ -0,0 +1,67 @@
+name: Helm chart
+
+on:
+ workflow_dispatch:
+ pull_request:
+ branches:
+ - main
+ paths:
+ - 'deploy/activepieces-helm/**'
+ - '.github/workflows/helm-chart.yml'
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ install:
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ defaults:
+ run:
+ working-directory: deploy/activepieces-helm
+ steps:
+ - uses: actions/checkout@v5
+
+ - uses: azure/setup-helm@v4
+
+ - name: Lint and render with default values
+ run: |
+ helm repo add mittwald https://helm.mittwald.de
+ helm repo add bitnami https://charts.bitnami.com/bitnami
+ helm dependency build
+ helm lint .
+ helm template ap . | grep -q '^kind: Rollout'
+ helm template ap . --api-versions apps/v1/StatefulSet | grep -q '^kind: StatefulSet'
+ helm template ap . --set autoscaling.enabled=true --api-versions apps/v1/StatefulSet --api-versions argoproj.io/v1alpha1/Rollout > "$RUNNER_TEMP/rollout.yaml"
+ grep -q '^kind: Rollout' "$RUNNER_TEMP/rollout.yaml"
+ grep -q 'name: ap-activepieces-preview' "$RUNNER_TEMP/rollout.yaml"
+ grep -A2 'scaleTargetRef:' "$RUNNER_TEMP/rollout.yaml" | grep -q 'kind: Rollout'
+
+ - uses: helm/kind-action@v1
+
+ - name: Create connection secrets
+ run: |
+ kubectl create secret generic activepieces-config-secrets --from-literal=AP_FRONTEND_URL=http://ap-activepieces.default.svc.cluster.local
+ kubectl create secret generic activepieces-db-secrets --from-literal=AP_POSTGRES_HOST=ap-postgresql --from-literal=AP_POSTGRES_PORT=5432 --from-literal=AP_POSTGRES_DATABASE=postgres --from-literal=AP_POSTGRES_USERNAME=postgres --from-literal=AP_POSTGRES_PASSWORD=ci-password
+ kubectl create secret generic activepieces-redis-secrets --from-literal=AP_REDIS_HOST=ap-redis-master --from-literal=AP_REDIS_PORT=6379 --from-literal=AP_REDIS_PASSWORD=ci-password
+
+ - name: Install
+ run: |
+ helm install ap . --wait --timeout 10m \
+ --set image.tag=latest \
+ --set persistence.storageClassName=standard \
+ --set postgresql.enabled=true,postgresql.auth.postgresPassword=ci-password \
+ --set redis.enabled=true,redis.architecture=standalone,redis.auth.password=ci-password
+
+ - name: Test
+ run: |
+ kubectl get statefulset ap-activepieces
+ helm test ap
+
+ - name: Debug
+ if: failure()
+ run: |
+ kubectl get pods
+ kubectl describe pods
+ kubectl logs statefulset/ap-activepieces --tail 200 || true
diff --git a/.github/workflows/release-self-hosted.yml b/.github/workflows/release-self-hosted.yml
index 578d6ff59f4..4277b30f0af 100644
--- a/.github/workflows/release-self-hosted.yml
+++ b/.github/workflows/release-self-hosted.yml
@@ -55,6 +55,11 @@ jobs:
exit 1
fi
echo "Release tag base '$TAG_BASE' matches package.json version '$PACKAGE_VERSION'."
+ CHART_APP_VERSION="$(sed -n 's/^appVersion: "\(.*\)"/\1/p' deploy/activepieces-helm/Chart.yaml)"
+ if [ "$CHART_APP_VERSION" != "$PACKAGE_VERSION" ]; then
+ echo "::error::Helm chart appVersion '$CHART_APP_VERSION' does not match package.json version '$PACKAGE_VERSION'. Bump deploy/activepieces-helm/Chart.yaml."
+ exit 1
+ fi
- name: Fail if tag already exists
run: '! docker manifest inspect activepieces/activepieces:${{ inputs.tag }}'
@@ -166,8 +171,9 @@ jobs:
npm pkg set version="$TAG_BASE"
sed -i -E "s|(image: ghcr.io/activepieces/activepieces:)[0-9][0-9a-zA-Z.-]*|\1$TAG|" docker-compose.yml
grep -q "image: ghcr.io/activepieces/activepieces:$TAG" docker-compose.yml
+ sed -i -E "s|^appVersion: .*|appVersion: \"$TAG_BASE\"|" deploy/activepieces-helm/Chart.yaml
git checkout -b "automated/sync-version-$TAG_BASE"
- git add package.json docker-compose.yml
+ git add package.json docker-compose.yml deploy/activepieces-helm/Chart.yaml
git commit -m "chore(release): sync version to $TAG_BASE after off-cycle release"
git push -f origin "automated/sync-version-$TAG_BASE"
diff --git a/brain/knowledge/decisions/000040-helm-chart-keys-are-generated-in-cluster-and-user-secrets-override-them.md b/brain/knowledge/decisions/000040-helm-chart-keys-are-generated-in-cluster-and-user-secrets-override-them.md
new file mode 100644
index 00000000000..198fb3c2b37
--- /dev/null
+++ b/brain/knowledge/decisions/000040-helm-chart-keys-are-generated-in-cluster-and-user-secrets-override-them.md
@@ -0,0 +1,21 @@
+---
+status: accepted
+---
+
+# Helm chart keys are generated in-cluster, and user secrets override them
+
+## Decision
+
+The chart gets `AP_ENCRYPTION_KEY` and `AP_JWT_SECRET` from the mittwald `secret-generator` subchart, which fills `<fullname>-secrets` and `<fullname>-jwt-secret` in-cluster. The pod reads them through `envFrom`. A user-created `activepieces-auth-secrets` is mapped through `env`, so it wins at runtime.
+
+## Context
+
+GIT-1923: after worker v2 the generated secrets were never wired in, so a default install crashlooped. Users who worked around it had already created `activepieces-auth-secrets` with their own keys, and their stored data is encrypted with those keys.
+
+## Why
+
+`lookup` + `randAlphaNum` regenerates the key on every `helm template` / ArgoCD render, which would silently rotate the encryption key. Rendering one env name twice to get precedence gets rejected by Helm 4's server-side apply. `env` over `envFrom` gives the runtime fallback without either problem, and upgrades change nothing for existing users.
+
+## Consequences
+
+Renaming the generated keys or secrets orphans every install's key. A user key present at render time is pinned (`optional: false`), so the fallback only ever serves installs that never had their own key. The chart keeps a cluster-scoped operator as a dependency.
diff --git a/brain/knowledge/engineering/helm-chart.md b/brain/knowledge/engineering/helm-chart.md
index f707d1dcdbf..451545e08bd 100644
--- a/brain/knowledge/engineering/helm-chart.md
+++ b/brain/knowledge/engineering/helm-chart.md
@@ -10,15 +10,25 @@ The Kubernetes install we ship to self-hosters, at `deploy/activepieces-helm/`.
`templates/deployment.yaml` builds one `env:` list from two values keys, in this fixed order:
- **`activepiecesConfig`** — a flat map rendered as plain `value:` entries. Rendered **first**. The shipped default holds only `AP_CONTAINER_TYPE`.
-- **`activepiecesEnvVariables`** — a map of *secret name* → *list of var names*, rendered as `secretKeyRef` with `optional: true`. Rendered **second**. The shipped default routes `AP_EDITION`, `AP_EXECUTION_MODE`, `AP_ENCRYPTION_KEY`, `AP_JWT_SECRET` and the queue/auth vars through three secrets the chart does not create.
+- **`activepiecesEnvVariables`** — a map of *secret name* → *list of var names*, rendered as `secretKeyRef` with `optional: true`. Rendered **second**. The shipped default routes `AP_EDITION`, `AP_EXECUTION_MODE`, `AP_ENCRYPTION_KEY`, `AP_JWT_SECRET` and the queue/auth vars through secrets the chart does not create.
+- **`envFrom` the generated secrets**: lowest precedence. Supplies `AP_ENCRYPTION_KEY` / `AP_JWT_SECRET` when no user secret sets them, because `env` beats `envFrom`.
## What the chart creates
-Only two secrets, both `data: {}` with mittwald `secret-generator` annotations that fill them in-cluster: `<release>-secrets` (encryption key) and `<release>-jwt-secret`. Postgres and Redis come from the Bitnami subcharts unless disabled.
+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`, and `templates/`
## Gotchas
- **Setting the same `AP_*` var in both values keys puts two entries with one name in the pod spec, and the secret wins.** `activepiecesConfig` renders before `activepiecesEnvVariables`, and for duplicate env names the later entry is what the container process sees. Since the shipped `values.yaml` already lists `AP_EDITION` and `AP_EXECUTION_MODE` under `activepieces-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: true` saves 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.
-- **`activepieces-config-secrets`, `activepieces-auth-secrets` and `activepieces-queue-secrets` do not exist until you make them, and the script `values.yaml` names for the job is not in the repo.** The comment points at `deploy/scripts/apply-secrets.sh --secret-name <name>`; there is no `deploy/scripts/` directory. Every ref is `optional: true`, so a fresh `helm install` comes up anyway on the app's own defaults — which is why the gap survived: nothing fails, the vars are just quietly absent.
+- **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. `localhost` Postgres), even with the subcharts enabled.
+- **Offline renders can't see the cluster.** Helm's default `.Capabilities.APIVersions` has group/version entries only; a connected install adds kind-level ones such as `apps/v1/StatefulSet`. That is the only live-cluster signal that works with `--create-namespace` and restricted RBAC (a `lookup` sees no namespace yet and errors on Forbidden).
+- **A user-owned key is pinned once it exists.** If `AP_ENCRYPTION_KEY` / `AP_JWT_SECRET` are in the user's secret when the chart renders, their `secretKeyRef` becomes `optional: 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 `env` keys ("duplicate entries for key"). A lower-precedence default has to come through `envFrom`.
+- **Removing a duplicate env name on a Helm 3 upgrade deletes both entries.** The strategic merge patch matches `env` items 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.
+- **`AP_FRONTEND_URL` must be reachable from inside the pod.** The worker downloads piece bundles through the public URL, so a `localhost` value boots fine and then fails every flow with `fetch failed`.
+- **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 uninstall` leaves it behind. A second release can set `kubernetes-secret-generator.enabled: false`; the first operator watches every namespace.
+- **Helm 4 upgrades of a `Rollout` need `--force-conflicts`.** Argo's controller owns the Service `.spec.selector` (it adds `rollouts-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.workloadType` resolves to.** It used to target a `Deployment` the chart never creates.
+- **`Chart.yaml` `appVersion` is the default image tag.** `release-self-hosted.yml` fails the release if it drifts from `package.json`, and the version sync PR bumps it.
- **`AP_EDITION=ee` needs `AP_EXECUTION_MODE` set in the same breath or the pod will not boot.** `system-validator.ts` throws for `cloud`/`ee` in production unless the mode is one of `SANDBOX_PROCESS`, `SANDBOX_CODE_ONLY`, `SANDBOX_CODE_AND_PROCESS`, and the default is `UNSANDBOXED`. The error names the execution mode, not the edition, so it reads as a sandboxing problem rather than the edition switch that caused it.
diff --git a/deploy/activepieces-helm/Chart.yaml b/deploy/activepieces-helm/Chart.yaml
index 9b63e2aaf93..6e3d033116a 100644
--- a/deploy/activepieces-helm/Chart.yaml
+++ b/deploy/activepieces-helm/Chart.yaml
@@ -16,13 +16,13 @@ type: application
# This is the chart version. This version number should be incremented each time you make changes
# to the chart and its templates, including the app version.
# Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 0.3.0
+version: 0.4.0
# This is the version number of the application being deployed. This version number should be
# incremented each time you make changes to the application. Versions are not expected to
# follow Semantic Versioning. They should reflect the version the application is using.
# It is recommended to use it with quotes.
-appVersion: "0.71.2"
+appVersion: "0.92.0"
dependencies:
- name: kubernetes-secret-generator
diff --git a/deploy/activepieces-helm/templates/_helpers.tpl b/deploy/activepieces-helm/templates/_helpers.tpl
index 14c66b5e843..34d574caff5 100644
--- a/deploy/activepieces-helm/templates/_helpers.tpl
+++ b/deploy/activepieces-helm/templates/_helpers.tpl
@@ -60,3 +60,15 @@ Create the name of the service account to use
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}
+
+{{- define "activepieces.workloadType" -}}
+{{- $liveCluster := .Capabilities.APIVersions.Has "apps/v1/StatefulSet" }}
+{{- $argoRollouts := .Capabilities.APIVersions.Has "argoproj.io/v1alpha1/Rollout" }}
+{{- if .Values.workloadType }}
+{{- .Values.workloadType }}
+{{- else if and $liveCluster (not $argoRollouts) (not (lookup "v1" "Service" .Release.Namespace (printf "%s-preview" (include "activepieces.fullname" .)))) }}
+{{- "statefulset" }}
+{{- else }}
+{{- "rollout" }}
+{{- end }}
+{{- end }}
diff --git a/deploy/activepieces-helm/templates/deployment.yaml b/deploy/activepieces-helm/templates/deployment.yaml
index e7e2c431733..ecbcb4074ad 100644
--- a/deploy/activepieces-helm/templates/deployment.yaml
+++ b/deploy/activepieces-helm/templates/deployment.yaml
@@ -1,4 +1,4 @@
-{{- if eq (.Values.workloadType | default "rollout") "statefulset" }}
+{{- if eq (include "activepieces.workloadType" .) "statefulset" }}
apiVersion: apps/v1
kind: StatefulSet
{{- else }}
@@ -13,7 +13,7 @@ spec:
{{- if not .Values.autoscaling.enabled }}
replicas: {{ .Values.replicaCount }}
{{- end }}
- {{- if eq (.Values.workloadType | default "rollout") "statefulset" }}
+ {{- if eq (include "activepieces.workloadType" .) "statefulset" }}
serviceName: {{ include "activepieces.fullname" . }}
podManagementPolicy: {{ .Values.podManagementPolicy | default "OrderedReady" }}
{{- end }}
@@ -54,6 +54,11 @@ spec:
- name: http
containerPort: {{ .Values.container.port }}
protocol: TCP
+ envFrom:
+ - secretRef:
+ name: {{ include "activepieces.fullname" . }}-secrets
+ - secretRef:
+ name: {{ include "activepieces.fullname" . }}-jwt-secret
{{- if or .Values.activepiecesEnvVariables .Values.activepiecesConfig }}
env:
{{- range $key, $value := .Values.activepiecesConfig }}
@@ -62,12 +67,16 @@ spec:
{{- end }}
{{- range $secretName, $vars := .Values.activepiecesEnvVariables }}
{{- range $vars }}
+ {{- $userOwnedKey := false }}
+ {{- if has . (list "AP_ENCRYPTION_KEY" "AP_JWT_SECRET") }}
+ {{- $userOwnedKey = hasKey ((lookup "v1" "Secret" $.Release.Namespace $secretName).data | default dict) . }}
+ {{- end }}
- name: {{ . }}
valueFrom:
secretKeyRef:
name: {{ $secretName | quote }}
key: {{ . }}
- optional: true
+ optional: {{ not $userOwnedKey }}
{{- end }}
{{- end }}
{{- end }}
@@ -95,7 +104,7 @@ spec:
{{- end }}
{{- if or .Values.persistence.enabled .Values.volumes }}
volumes:
- {{- if and .Values.persistence.enabled (ne (.Values.workloadType | default "rollout") "statefulset") }}
+ {{- if and .Values.persistence.enabled (ne (include "activepieces.workloadType" .) "statefulset") }}
- name: cache
persistentVolumeClaim:
claimName: {{ include "activepieces.fullname" . }}-cache
@@ -116,7 +125,7 @@ spec:
tolerations:
{{- toYaml . | nindent 8 }}
{{- end }}
- {{- if eq (.Values.workloadType | default "rollout") "statefulset" }}
+ {{- if eq (include "activepieces.workloadType" .) "statefulset" }}
{{- if .Values.persistence.enabled }}
volumeClaimTemplates:
- metadata:
diff --git a/deploy/activepieces-helm/templates/hpa.yaml b/deploy/activepieces-helm/templates/hpa.yaml
index 20415a405a3..431453f7047 100644
--- a/deploy/activepieces-helm/templates/hpa.yaml
+++ b/deploy/activepieces-helm/templates/hpa.yaml
@@ -7,8 +7,13 @@ metadata:
{{- include "activepieces.labels" . | nindent 4 }}
spec:
scaleTargetRef:
+ {{- if eq (include "activepieces.workloadType" .) "statefulset" }}
apiVersion: apps/v1
- kind: Deployment
+ kind: StatefulSet
+ {{- else }}
+ apiVersion: argoproj.io/v1alpha1
+ kind: Rollout
+ {{- end }}
name: {{ include "activepieces.fullname" . }}
minReplicas: {{ .Values.autoscaling.minReplicas }}
maxReplicas: {{ .Values.autoscaling.maxReplicas }}
diff --git a/deploy/activepieces-helm/templates/pvc.yaml b/deploy/activepieces-helm/templates/pvc.yaml
index f466ab5103d..a03b5a157f3 100644
--- a/deploy/activepieces-helm/templates/pvc.yaml
+++ b/deploy/activepieces-helm/templates/pvc.yaml
@@ -1,4 +1,4 @@
-{{- if and .Values.persistence.enabled (ne (.Values.workloadType | default "rollout") "statefulset") }}
+{{- if and .Values.persistence.enabled (ne (include "activepieces.workloadType" .) "statefulset") }}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
diff --git a/deploy/activepieces-helm/templates/secret.yaml b/deploy/activepieces-helm/templates/secret.yaml
index 930c8d8760d..4cfb4cb993e 100644
--- a/deploy/activepieces-helm/templates/secret.yaml
+++ b/deploy/activepieces-helm/templates/secret.yaml
@@ -5,7 +5,7 @@ metadata:
labels:
{{- include "activepieces.labels" . | nindent 4 }}
annotations:
- secret-generator.v1.mittwald.de/autogenerate: encryption-key
+ secret-generator.v1.mittwald.de/autogenerate: AP_ENCRYPTION_KEY
secret-generator.v1.mittwald.de/encoding: hex
secret-generator.v1.mittwald.de/length: "32"
type: Opaque
@@ -18,7 +18,7 @@ metadata:
labels:
{{- include "activepieces.labels" . | nindent 4 }}
annotations:
- secret-generator.v1.mittwald.de/autogenerate: jwt-secret
+ secret-generator.v1.mittwald.de/autogenerate: AP_JWT_SECRET
secret-generator.v1.mittwald.de/length: "64"
type: Opaque
data: {}
\ No newline at end of file
diff --git a/deploy/activepieces-helm/templates/service.yaml b/deploy/activepieces-helm/templates/service.yaml
index d20a62fec79..6713b7a74b5 100644
--- a/deploy/activepieces-helm/templates/service.yaml
+++ b/deploy/activepieces-helm/templates/service.yaml
@@ -17,7 +17,7 @@ spec:
name: api
selector:
{{- include "activepieces.selectorLabels" . | nindent 4 }}
-{{- if ne (.Values.workloadType | default "rollout") "statefulset" }}
+{{- if ne (include "activepieces.workloadType" .) "statefulset" }}
---
apiVersion: v1
kind: Service
diff --git a/deploy/activepieces-helm/values.yaml b/deploy/activepieces-helm/values.yaml
index e4b6ff96c34..b574d7965c5 100644
--- a/deploy/activepieces-helm/values.yaml
+++ b/deploy/activepieces-helm/values.yaml
@@ -111,6 +111,11 @@ autoscaling:
targetCPUUtilizationPercentage: 80
# targetMemoryUtilizationPercentage: 80
+rollout:
+ blueGreen:
+ autoPromotionEnabled: true
+ scaleDownDelaySeconds: 30
+
persistence:
enabled: true
size: 2Gi
@@ -138,6 +143,8 @@ affinity: {}
# ============================================================================
postgresql:
enabled: false
+ image:
+ repository: bitnamilegacy/postgresql
# auth:
# database: activepieces
# username: postgres
@@ -160,6 +167,8 @@ postgresql:
# ============================================================================
redis:
enabled: false
+ image:
+ repository: bitnamilegacy/redis
# auth:
# enabled: true
# password: "" # leave empty to auto-generate
@@ -175,7 +184,6 @@ activepiecesConfig:
# Map of Kubernetes secret name → list of AP_* (and OTEL_*) env var names to inject.
# Each var name must exist as a key in the corresponding secret.
-# Populate secrets with deploy/scripts/apply-secrets.sh --secret-name <name> before deploying.
activepiecesEnvVariables:
activepieces-config-secrets:
- AP_EDITION
diff --git a/docs/install/options/helm.mdx b/docs/install/options/helm.mdx
index 2e363b91928..88e349bce38 100644
--- a/docs/install/options/helm.mdx
+++ b/docs/install/options/helm.mdx
@@ -13,87 +13,37 @@ This guide walks you through deploying Activepieces on Kubernetes using the offi
- Helm 3.x installed
- kubectl configured to access your cluster
-## Using External PostgreSQL and Redis
+When `helm install` or `helm upgrade` talks to a cluster without [Argo Rollouts](https://argoproj.github.io/rollouts/), the chart deploys a `StatefulSet`; otherwise it deploys an Argo `Rollout`. A release that already runs as a `Rollout` stays one. Rendering without a cluster (`helm template`, Kustomize) produces a `Rollout`, so set `workloadType: statefulset` there, or pass the cluster's API versions as Argo CD does. The StatefulSet volume uses the `local-path` storage class unless you set `persistence.storageClassName`.
-The Helm chart supports using external PostgreSQL and Redis services instead of deploying the Bitnami subcharts.
+## Database and Redis
-### Using External PostgreSQL
+The chart reads PostgreSQL and Redis settings from the secrets listed under `activepiecesEnvVariables` in `values.yaml`. Create them before installing:
-To use an external PostgreSQL instance:
+Put the settings in env files, so passwords stay out of your shell history and process list. Run `umask 077` first so only you can read them:
-```yaml
-postgresql:
- enabled: false # Disable Bitnami PostgreSQL subchart
- host: "your-postgres-host.example.com"
- port: 5432
- useSSL: true # Enable SSL if required
- auth:
- database: "activepieces"
- username: "postgres"
- password: "your-password"
- # Or use external secret reference:
- # externalSecret:
- # name: "postgresql-credentials"
- # key: "password"
+```bash title="db.env"
+AP_POSTGRES_HOST=your-postgres-host.example.com
+AP_POSTGRES_PORT=5432
+AP_POSTGRES_DATABASE=activepieces
+AP_POSTGRES_USERNAME=postgres
+AP_POSTGRES_PASSWORD=your-password
```
-Alternatively, you can use a connection URL:
-
-```yaml
-postgresql:
- enabled: false
- url: "postgresql://user:password@host:5432/database?sslmode=require"
+```bash title="redis.env"
+AP_REDIS_HOST=your-redis-host.example.com
+AP_REDIS_PORT=6379
+AP_REDIS_PASSWORD=your-password
```
-### Using External Redis
-
-To use an external Redis instance:
-
-```yaml
-redis:
- enabled: false # Disable Bitnami Redis subchart
- host: "your-redis-host.example.com"
- port: 6379
- useSSL: false # Enable SSL if required
- auth:
- enabled: true
- password: "your-password"
- # Or use external secret reference:
- # externalSecret:
- # name: "redis-credentials"
- # key: "password"
-```
-
-Alternatively, you can use a connection URL:
-
-```yaml
-redis:
- enabled: false
- url: "redis://:password@host:6379/0"
+```bash
+kubectl create secret generic activepieces-db-secrets --from-env-file=db.env
+kubectl create secret generic activepieces-redis-secrets --from-env-file=redis.env
+rm db.env redis.env
```
-### External Secret References
+To run PostgreSQL and Redis inside the cluster instead, set `postgresql.enabled: true` / `redis.enabled: true`. The hosts are `<release>-postgresql` and `<release>-redis-master`.
-For better security, you can reference passwords from existing Kubernetes secrets (useful with External Secrets Operator or Sealed Secrets):
-
-```yaml
-postgresql:
- enabled: false
- host: "your-postgres-host.example.com"
- auth:
- externalSecret:
- name: "postgresql-credentials"
- key: "password"
-
-redis:
- enabled: false
- host: "your-redis-host.example.com"
- auth:
- enabled: true
- externalSecret:
- name: "redis-credentials"
- key: "password"
-```
+`AP_JWT_SECRET` and `AP_ENCRYPTION_KEY` are generated on first install. To bring your own, put them in `activepieces-auth-secrets`; that secret takes precedence.
## Quick Start
@@ -107,7 +57,9 @@ cd activepieces
### 2. Install Dependencies
```bash
-helm dependency update
+helm repo add mittwald https://helm.mittwald.de
+helm repo add bitnami https://charts.bitnami.com/bitnami
+helm dependency build deploy/activepieces-helm
```
### 3. Create a Values File
@@ -115,21 +67,28 @@ helm dependency update
Create a `my-values.yaml` file with your configuration. You can use the [example values file](https://github.com/activepieces/activepieces/blob/main/deploy/activepieces-helm/values.yaml) as a reference.
The Helm chart has sensible defaults for required values while leaving the optional ones empty, but you should customize these core values for production.
-Include these so you can activate a [license key](/install/configure-operate/enterprise-license) later:
+Set the core settings in the `activepieces-config-secrets` secret the chart already reads. `AP_EDITION` and `AP_EXECUTION_MODE` let you activate a [license key](/install/configure-operate/enterprise-license) later:
+
+```bash
+kubectl create secret generic activepieces-config-secrets \
+ --from-literal=AP_FRONTEND_URL=https://activepieces.yourdomain.com \
+ --from-literal=AP_EDITION=ee \
+ --from-literal=AP_EXECUTION_MODE=SANDBOX_CODE_ONLY
+```
+
+`AP_FRONTEND_URL` is required, and it must also be reachable from inside the pod: the worker downloads pieces through it.
```yaml
-activepiecesConfig:
- AP_EDITION: "ee"
- AP_EXECUTION_MODE: "SANDBOX_CODE_ONLY"
+persistence:
+ storageClassName: "your-storage-class" # see `kubectl get storageclass`
```
<Warning>
-Set both, and set each variable in **one place only**. `activepiecesConfig` writes plain values into the pod, while `activepiecesEnvVariables` pulls the same names from Kubernetes secrets you create yourself and renders *after* it, so a secret that holds the key wins. The chart lists `AP_EDITION` and `AP_EXECUTION_MODE` under `activepieces-config-secrets` by default, so either remove them from there or set them in that secret instead of here.
+Set `AP_EDITION` and `AP_EXECUTION_MODE` together: `AP_EDITION=ee` with the default execution mode is rejected at startup and the app will not boot.
-`AP_EDITION=ee` with the default execution mode is rejected at startup and the app will not boot.
+Set each variable in **one place only**. A name that is both in `activepiecesConfig` and in an `activepiecesEnvVariables` list is rendered twice, which Helm 4 rejects (`duplicate entries for key`).
</Warning>
-
### 4. Install Activepieces
```bash
@@ -147,7 +106,7 @@ kubectl get services
## Production Checklist
-- [ ] Set `frontendUrl` to your actual domain
+- [ ] Set `AP_FRONTEND_URL` to your actual domain
- [ ] Set strong passwords for PostgreSQL and Redis (or keep auto-generated)
- [ ] Configure proper ingress with TLS
- [ ] Set appropriate resource limits
@@ -160,29 +119,35 @@ kubectl get services
```bash
# Update dependencies
-helm dependency update
+helm dependency build deploy/activepieces-helm
# Upgrade release
helm upgrade activepieces deploy/activepieces-helm -f my-values.yaml
-# Check upgrade status
-kubectl rollout status deployment/activepieces
+# Check upgrade status (StatefulSet)
+kubectl rollout status statefulset/activepieces
+# Check upgrade status (Argo Rollout)
+kubectl wait --for=jsonpath='{.status.phase}'=Healthy rollout/activepieces --timeout=10m
```
+With Helm 4 and `workloadType: rollout`, add `--force-conflicts` to `helm upgrade`. Argo Rollouts owns the Service selectors, and Helm 4's server-side apply stops on that conflict otherwise.
+
+The bundled secret generator creates cluster-wide RBAC named after the release, so give each release in a cluster its own name. A second release can also set `kubernetes-secret-generator.enabled: false`, because the first release's generator already serves every namespace.
+
## Troubleshooting
### Common Issues
-1. **Pod won't start**: Check logs with `kubectl logs deployment/activepieces`
+1. **Pod won't start**: Check logs with `kubectl logs -l app.kubernetes.io/instance=activepieces,app.kubernetes.io/name=activepieces`
2. **Database connection**: Verify PostgreSQL credentials and connectivity
-3. **Frontend URL**: Ensure `frontendUrl` is accessible from external sources
+3. **Frontend URL**: Ensure `AP_FRONTEND_URL` is accessible from external sources
4. **Webhooks not working**: Check ingress configuration and DNS resolution
### Useful Commands
```bash
# View logs
-kubectl logs deployment/activepieces -f
+kubectl logs -l app.kubernetes.io/instance=activepieces,app.kubernetes.io/name=activepieces -f
# Port forward for testing
kubectl port-forward svc/activepieces 4200:80 --namespace default