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
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
fix(helm): OpenShift overlay, and the cluster's default storage class when none is set (#16033)
Amr Elmohamady0a6570d2f0a3
diff --git a/brain/knowledge/engineering/helm-chart.md b/brain/knowledge/engineering/helm-chart.mdindex 94e6f8295a0..83b90f870bd 100644--- a/brain/knowledge/engineering/helm-chart.md+++ b/brain/knowledge/engineering/helm-chart.md@@ -36,3 +36,7 @@ Only two secrets, both `data: {}` with mittwald `secret-generator` annotations t- **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.+- **Bumping the bundled Bitnami subcharts is a database migration, not a version bump.** `postgresql` past 11.7.2 ships PostgreSQL 17, which will not start on the 14 data directory, so every bundled-DB install needs a dump, a fresh `data-<release>-postgresql-0` claim 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 under `bitnamilegacy/*` 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.yaml` moves 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 so `SANDBOX_PROCESS` installs keep working. The overlay must never set `runAsUser` / `fsGroup` (restricted-v2 rejects IDs outside the project's range) or `AP_EXECUTION_MODE` (the shipped values already read it from a secret, so it would render twice). See GIT-1929.+- **An empty `persistence.storageClassName` keeps whatever class the live StatefulSet already has.** A StatefulSet's `volumeClaimTemplates` are immutable, so any change there fails the whole `helm upgrade` ("updates to statefulset spec ... are forbidden"). `activepieces.cacheStorageClassName` looks 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 though `helm upgrade` survives it.+- **A failed `helm upgrade` is 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.diff --git a/deploy/activepieces-helm/Chart.yaml b/deploy/activepieces-helm/Chart.yamlindex 6e3d033116a..d71051a12f1 100644--- a/deploy/activepieces-helm/Chart.yaml+++ b/deploy/activepieces-helm/Chart.yaml@@ -16,7 +16,7 @@ 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.4.0+version: 0.5.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 todiff --git a/deploy/activepieces-helm/templates/_helpers.tpl b/deploy/activepieces-helm/templates/_helpers.tplindex 34d574caff5..3d9ab5d326d 100644--- a/deploy/activepieces-helm/templates/_helpers.tpl+++ b/deploy/activepieces-helm/templates/_helpers.tpl@@ -72,3 +72,17 @@ Create the name of the service account to use{{- "rollout" }}{{- end }}{{- end }}++{{- define "activepieces.cacheStorageClassName" -}}+{{- if .Values.persistence.storageClassName }}+{{- .Values.persistence.storageClassName }}+{{- else }}+{{- with lookup "apps/v1" "StatefulSet" .Release.Namespace (include "activepieces.fullname" .) }}+{{- range .spec.volumeClaimTemplates }}+{{- if eq .metadata.name "cache" }}+{{- .spec.storageClassName | default "" }}+{{- end }}+{{- end }}+{{- end }}+{{- end }}+{{- end }}diff --git a/deploy/activepieces-helm/templates/deployment.yaml b/deploy/activepieces-helm/templates/deployment.yamlindex c7e29e5eb5d..fda211c0761 100644--- a/deploy/activepieces-helm/templates/deployment.yaml+++ b/deploy/activepieces-helm/templates/deployment.yaml@@ -138,7 +138,9 @@ spec:name: cachespec:accessModes: [ "ReadWriteOnce" ]- storageClassName: {{ .Values.persistence.storageClassName | default "local-path" | quote }}+ {{- with include "activepieces.cacheStorageClassName" . }}+ storageClassName: {{ . | quote }}+ {{- end }}resources:requests:storage: {{ .Values.persistence.size | quote }}diff --git a/deploy/activepieces-helm/values-openshift.yaml b/deploy/activepieces-helm/values-openshift.yamlnew file mode 100644index 00000000000..cca245b6560--- /dev/null+++ b/deploy/activepieces-helm/values-openshift.yaml@@ -0,0 +1,66 @@+# Overlay for OpenShift 4.x under the default `restricted-v2` SCC.+#+# Install:+# helm install activepieces deploy/activepieces-helm \+# -f deploy/activepieces-helm/values.yaml \+# -f deploy/activepieces-helm/values-openshift.yaml \+# -f my-values.yaml+#+# What this overlay changes vs. the base chart:+# - Port moves above 1024 so a non-root pod can bind without NET_BIND_SERVICE.+# - securityContext hardened: non-root, no capabilities, seccomp RuntimeDefault.+# No runAsUser / fsGroup: the SCC assigns both from the project's range, and a+# fixed ID outside that range is rejected at admission.+# - storageClassName left empty so the cluster's default class is used.+# - The bundled PostgreSQL and Redis subcharts hardcode user ID 1001, which+# restricted-v2 rejects; their security contexts are turned off so the SCC+# assigns the IDs instead.+#+# Set AP_EXECUTION_MODE to SANDBOX_CODE_ONLY (or UNSANDBOXED) in the+# activepieces-config-secrets secret, not here: SANDBOX_PROCESS and+# SANDBOX_CODE_AND_PROCESS need CAP_SYS_ADMIN, which restricted-v2 never grants.++podSecurityContext:+ runAsNonRoot: true+ seccompProfile:+ type: RuntimeDefault++securityContext:+ runAsNonRoot: true+ allowPrivilegeEscalation: false+ capabilities:+ drop:+ - ALL++container:+ port: 8080++persistence:+ storageClassName: ""++activepiecesConfig:+ AP_PORT: "8080"++postgresql:+ primary:+ podSecurityContext:+ enabled: false+ containerSecurityContext:+ enabled: false+ readReplicas:+ podSecurityContext:+ enabled: false+ containerSecurityContext:+ enabled: false++redis:+ master:+ podSecurityContext:+ enabled: false+ containerSecurityContext:+ enabled: false+ replica:+ podSecurityContext:+ enabled: false+ containerSecurityContext:+ enabled: falsediff --git a/deploy/activepieces-helm/values.yaml b/deploy/activepieces-helm/values.yamlindex 46efb289222..0de64d77a41 100644--- a/deploy/activepieces-helm/values.yaml+++ b/deploy/activepieces-helm/values.yaml@@ -120,6 +120,8 @@ persistence:enabled: truesize: 2GimountPath: "/usr/src/app/cache"+ # Leave empty to use the cluster's default StorageClass.+ storageClassName: ""volumes: []volumeMounts: []diff --git a/docs/install/options/helm.mdx b/docs/install/options/helm.mdxindex a0102bbd55a..ed7067ed48f 100644--- a/docs/install/options/helm.mdx+++ b/docs/install/options/helm.mdx@@ -13,7 +13,7 @@ This guide walks you through deploying Activepieces on Kubernetes using the offi- Helm 3.x installed- kubectl configured to access your cluster-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`.+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 cluster's default StorageClass unless you set `persistence.storageClassName`. On a cluster without a default class (`kubectl get storageclass` shows none marked `(default)`), set it, or the pod stays `Pending`. Choose it before the first install: a StatefulSet's volume class cannot change afterwards.## Database and Redis@@ -196,6 +196,27 @@ kubectl delete statefulset "$FULLNAME"kubectl delete pvc "cache-$FULLNAME-0"```+## OpenShift++The base chart runs as root on port 80, which OpenShift's default `restricted-v2` SCC rejects with `listen EACCES :::80`. Add the OpenShift overlay on top of your own values:++```bash+helm install activepieces deploy/activepieces-helm \+ -f deploy/activepieces-helm/values.yaml \+ -f deploy/activepieces-helm/values-openshift.yaml \+ -f my-values.yaml+```++The overlay runs the pod as non-root on port 8080, drops all capabilities and uses the cluster's default StorageClass. It sets no user or group ID, so OpenShift assigns both from the project's range.++Set `AP_EXECUTION_MODE` to `SANDBOX_CODE_ONLY` in the `activepieces-config-secrets` secret, as in step 3. `SANDBOX_PROCESS` and `SANDBOX_CODE_AND_PROCESS` need `CAP_SYS_ADMIN`, which `restricted-v2` never grants. In `SANDBOX_CODE_ONLY`, code steps that import npm packages fail; see [Sandboxing](/install/architecture/sandboxing).++The bundled PostgreSQL and Redis subcharts hardcode user ID 1001, which `restricted-v2` rejects. The overlay turns off their security contexts and OpenShift assigns the IDs instead, so `postgresql.enabled` and `redis.enabled` need no extra settings.++The chart does not create an OpenShift `Route`. Create one pointing at the `activepieces` service on port 80, or use the `Ingress` under `ingress.*`.++To use the overlay on another cluster that enforces the Kubernetes `restricted` Pod Security profile, also set a non-root `runAsUser` and `fsGroup` (for example `1001`) under `podSecurityContext`: the image runs as root, and `runAsNonRoot` refuses to start it without one. Use external PostgreSQL and Redis there: with the overlay, the bundled database pods have no security context, which that profile rejects.+## Troubleshooting### Common Issuesdiff --git a/docs/install/reference/breaking-changes.mdx b/docs/install/reference/breaking-changes.mdxindex 4f9687a9cd0..0ba0ceabbb8 100644--- a/docs/install/reference/breaking-changes.mdx+++ b/docs/install/reference/breaking-changes.mdx@@ -8,6 +8,21 @@ icon: "hammer"### What has changed?+#### Helm chart 0.5.0 uses the cluster's default StorageClass again++Chart 0.4.0 set the app's cache volume to the `local-path` StorageClass whenever `persistence.storageClassName` was unset, which only exists on k3s-style clusters, so new installs elsewhere stayed `Pending`. From 0.5.0 an unset value uses the cluster's default StorageClass again, as chart 0.3.x did. A StatefulSet's volume class cannot change after it is created, so `helm upgrade` keeps the class your release already uses.++#### What you need to do++If your release was created with chart 0.4.0, you never set `persistence.storageClassName`, and you deploy by rendering the chart without a cluster connection (Argo CD, `helm template | kubectl apply`), pin the class your StatefulSet was created with before upgrading, or every sync fails with `updates to statefulset spec ... are forbidden`:++```yaml+persistence:+ storageClassName: "local-path"+```++Direct `helm upgrade` needs no change. A new install on a cluster with no default StorageClass (`kubectl get storageclass` shows none marked `(default)`) must set `persistence.storageClassName`, or the cache volume and the app pod stay `Pending`.+#### Zoho CRM Read File and Custom API Call only send the token to the connection's Zoho CRM hostsRead File used to send the connection's Zoho access token to whatever URL it was given, including hosts outside Zoho. From Zoho CRM 0.4.0 it only fetches `https` URLs on the connection's own Zoho API host under `/crm/` (for example `https://www.zohoapis.com/crm/bulk/v8/read/<job>/result`), or on that data centre's download hosts (for example `https://download-accl.zoho.com/v2/crm/...` for a data backup). Custom Zoho function URLs (`/crm/.../functions/...`) and URLs in another data centre are refused. Any other URL fails before a request is made. Redirects are followed only to those same hosts; a redirect anywhere else stops the download before that host is requested. The file is streamed, so the deployment's file size limit (`AP_MAX_FILE_SIZE_MB`) applies.