Version: 8.8 (unreleased)

Camunda 8.7 to 8.8 Helm chart upgrade

Upgrade from Camunda 8.7 to Camunda 8.8 by upgrading the Helm chart version from 12.x to 13.x.

Upgrade sequentially

Always upgrade from the latest patch of your current release → to the latest patch of the next release.

Example: from 12.x.x → 13.0.1 (not 13.0.0).

Check our version matrix for available versions.

Prerequisites

The following prerequisites are required before upgrading:

Prerequisite	Description
Helm chart version and Helm CLI version	Determine your Helm chart version and Helm CLI version and update them to the recommended versions listed in the version matrix.
Configuration changes	Ensure all required configuration changes in this guide are reviewed, understood, and implemented before running the `helm upgrade` command.
8.7 `values.yaml`	The approach described in this guide uses your existing 8.7 `values.yaml` file as a basis to create a new 8.8 `values.yaml`.

Recommended upgrade steps

The recommended approach is as follows:

Create 8.8 values.yaml: Copy your existing 8.7 values.yaml and use it as the basis for the new 8.8 file.
Update for 8.8 compatibility: Adjust the new values.yaml to match the changes in 8.8 and its updated architecture.
Prepare and run the upgrade: Add the required upgrade-specific configuration and steps, then execute the helm upgrade command.
Monitor and validate: Track the upgrade process and ensure all components start and function properly.

caution

During the upgrade, you must keep the same overall deployment setup. Configuration values must be updated where required for 8.8 compatibility, but architectural changes or switching authentication methods are not supported during the upgrade. For example, the same components should remain deployed, the same database connections used, and your authentication method must stay the same.

Step 1: Create 8.8 `values.yaml`

Copy your existing 8.7 values.yaml, rename it (for example, values-8.8.yaml), and use it as the basis for your 8.8 configuration.

note

Camunda 8.8 introduces major architectural and configuration changes. Using your 8.7 values.yaml as the starting point helps preserve your existing configuration wherever possible during the upgrade.

Step 2: Update for 8.8 compatibility

Go through the following sections and configure your new 8.8 values-8.8.yaml file to be compatible with the new 8.8 changes and architecture.

Key 8.8 changes

Review What’s new in Camunda 8.8
and Assess Camunda 8.8 changes and impact before proceeding with your upgrade from 8.7.

Overview of major changes

The following architectural and deployment changes related to the Helm Charts must be reviewed before upgrading:

Change	Description
Application consolidation	Zeebe, Zeebe Gateway, Operate, and Tasklist are consolidated into a single deployment artifact called the Orchestration Cluster.
Changed default deployment	By default, Camunda 8.8 deploys only the Orchestration Cluster, Connectors, and the Bitnami Elasticsearch subchart. The Orchestration Cluster keeps the StatefulSet name `zeebe` to avoid downtime. All other applications must be explicitly enabled in `values.yaml`. Per-application secondary storage retention is no longer supported.
Operate and Tasklist Importers	8.7 Operate and Tasklist importers are deployed as one importer deployment in 8.8 for the migration. They remain idle once migration is complete. You can scale them down manually. They will be removed entirely in 8.9.
Resource requirements	Resource allocation may need adjustment for the new Orchestration Cluster deployment. It’s recommended to run a load test simulating production traffic to ensure your cluster sizing is appropriate before upgrading your production environment.
Kubernetes migration jobs	Two Helm-based Kubernetes jobs support the migration: Identity migration Data migration
Elasticsearch/OpenSearch	Running dedicated Elasticsearch or OpenSearch clusters per app is no longer supported; only a shared cluster is allowed.
Metrics	Application metrics have been updated in 8.8; review and adapt your monitoring setup accordingly.
Multitenancy	A new configuration model is introduced. See Configure multi-tenancy in Helm chart.
Retention	Due to application consolidation, retention configuration per application is no longer supported. Retention policies must now be configured on Orchestration cluster level.
Ingress	Starting with Camunda 8.8, the separated Ingress configuration is no longer supported. Use the combined Ingress setup, or replicate the previous behavior as outlined in Configure Ingress.

Ensure required components

In 8.8, the default set of deployed components is different from 8.7 and you must select the Camunda components you want to deploy. The following components are enabled by default:

Orchestration Cluster
Connectors
Elasticsearch (Bitnami subchart)

All other components must be explicitly enabled in your values.yaml if you need them:

Console
Management Identity
Web Modeler
Optimize
PostgreSQL (Bitnami subchart)
Keycloak (Bitnami subchart)

Bitnami enterprise images

Because of to Bitnami’s support policy changes, Camunda now uses enterprise image. For more details and usage, see Bitnami enterprise images.

From 8.8 onwards, Bitnami subcharts for Keycloak and PostgreSQL are disabled.

Authentication

Make sure authentication is configured according to the following guidance:

Basic auth

Previously, in 8.7, if basic auth was enabled, it only applied to Operate and Tasklist. With 8.8, authentication now applies to the entire Orchestration Cluster. This means you must either migrate your users to the new cluster or reconfigure them accordingly. If you do not want to use authentication, you must explicitly disable it for Orchestration cluster; otherwise, users must be added to all requests. Ensure your values.yaml matches the configuration described in Basic authentication configuration.

OIDC

Ensure your values.yaml is configured according to the OIDC guide.

OAuth (Keycloak)

For an internal setup, follow the Internal Keycloak guide . For an external Keycloak deployment, make sure your values.yaml is configured as described in OpenID connect provider setup.

LDAP

No migration path is available. Please contact Camunda Consulting for support.

Migrate secrets to new format

Review the new secret conventions in 8.8 and upgrade your secrets accordingly.

Migrate to combined Ingress

Starting with Camunda 8.8, the separated ingress configuration is no longer supported. Use the combined Ingress setup, or replicate the previous behavior as outlined in Configure Ingress.

Multi-tenancy configuration

If you used multi-tenancy in 8.7, be aware that a new configuration model is introduced in 8.8. See Configure multi-tenancy in Helm chart for details.

Values key changes

Adjust your values.yaml for the 8.8 configuration changes, and double-check for any deprecated or renamed values.

Old key	New key	Notes
Web Modeler
`postgresql`	`webModelerPostgresql`

The consolidation of Zeebe, Zeebe Gateway, Operate, and Tasklist into the new Orchestration Cluster requires three types of changes:

Renamed keys - update references directly

Rename the top-level key zeebe to orchestration. Sub-keys remain the same.

Old key	New key	Notes
Zeebe
`zeebe`	`orchestration`

Relocated keys - move under orchestration

The following keys should be moved from the old components to orchestration.

Old key	New key	Notes
Global Identity Authintecation
`global.identity.auth.zeebe`	`orchestration.security.authentication.oidc`	⚠️ Different key name
Zeebe Gateway
`zeebeGateway.ingress`	`orchestration.ingress`
`zeebeGateway.contextPath`	`orchestration.contextPath`
`zeebeGateway.service.restPort`	`orchestration.service.httpPort`	⚠️ Different key name
`zeebeGateway.service.grpcPort`	`orchestration.service.grpcPort`
`zeebeGateway.service.commandPort`	`orchestration.service.commandPort`
`zeebeGateway.service.internalPort`	`orchestration.service.internalPort`
Operate
`operate.enabled`	`orchestration.profiles.operate`
Tasklist
`tasklist.enabled`	`orchestration.profiles.tasklist`

Relocated keys - move under Connectors

The following keys should be moved from global to connectors.

Old key	New key	Notes
Global Identity Authintecation
`global.identity.auth.connectors`	`connectors.security.authentication.oidc`	⚠️ Different key name

Merged keys - manually consolidate

These keys existed separately across components. They must now be combined under orchestration. If you use them, review carefully, as most accept free-form input.

Old key	New key	Notes
Configuration
`zeebe.configuration`	`orchestration.configuration`
`zeebeGateway.configuration`
`operate.configuration`
`tasklist.configuration`
ExtraConfiguration
`zeebe.extraConfiguration`	`orchestration.extraConfiguration`
`zeebeGateway.extraConfiguration`
`operate.extraConfiguration`
`tasklist.extraConfiguration`
Env
`zeebe.env`	`orchestration.env`
`zeebeGateway.env`
`operate.env`
`tasklist.env`
EnvFrom
`zeebe.envFrom`	`orchestration.envFrom`
`zeebeGateway.envFrom`
`operate.envFrom`
`tasklist.envFrom`
InitContainers
`zeebe.initContainers`	`orchestration.initContainers`
`zeebeGateway.initContainers`
`operate.initContainers`
`tasklist.initContainers`
Sidecars
`zeebe.sidecars`	`orchestration.sidecars`
`zeebeGateway.sidecars`
`operate.sidecars`
`tasklist.sidecars`
ExtraVolumes
`zeebe.extraVolumes`	`orchestration.extraVolumes`
`zeebeGateway.extraVolumes`
`operate.extraVolumes`
`tasklist.extraVolumes`
ExtraVolumeMounts
`zeebe.extraVolumeMounts`	`orchestration.extraVolumeMounts`
`zeebeGateway.extraVolumeMounts`
`operate.extraVolumeMounts`
`tasklist.extraVolumeMounts`

It is highly recommended to migrate to the new orchestration values structure. However, the Camunda 8.8 Helm chart (13.x.x) provides a compatibility layer, so configurations using the old structure from Camunda 8.7 (12.x.x) will still work. Enable the compatibility layer with:

global:
  compatibility:
    orchestration:
      enabled: true

Validate your new values.yaml

Before proceeding with the real upgrade, its strongly recommended to validate your new values-8.8.yaml with a greenfield installation.
This ensures your configuration is compatible with 8.8 and avoids having configuration issues on upgrade.

⚠️ Important: When performing this test installation, do not reuse your production resources.
Make sure to point the test installation to separate infrastructure (e.g., secrets, databases) so your production system remains unaffected.

helm repo add camunda https://helm.camunda.io
helm repo update

helm install camunda camunda/camunda-platform \
  --version 8.8.x \
  -f values-8.8.yaml

Run kubectl get pods and confirm that all pods are in the Running state. Once the test installation is successful, continue with Step 3: Prepare and run the upgrade below.

Step 3: Prepare and run the upgrade

Enable importer (required)

To finish processing existing 8.7 data prior to the migration, you must deploy the 8.7 importers. Without them, the migration cannot begin. Once the migration is complete, you can either disable the importers or leave them idle.

orchestration:
  importer:
    enabled: true

Data migration (required)

The Data Migration app is mandatory when upgrading from Camunda 8.7. It upgrades process data storage from the old 8.7 indices (tasklist-process, operate-process) to the new unified operate-process index in 8.8.

Important

Only supported when upgrading from 8.7 (not on fresh 8.8 installs). Can run only once. Requires that 8.7 already has process data; otherwise the job will fail.

Enable process migration in your values.yaml:

orchestration:
  migration:
    data:
      enabled: true

This creates a Kubernetes job and enables the Tasklist and Operate importers, which are necessary for migration to complete.

To confirm success, check the job logs or Prometheus metric:

camunda_migration_processes_migrated — should equal the number of documents in the operate-process index.

Identity migration (optional)

The Identity Migration app lets you move data from Management Identity (8.7) to the new Orchestration Cluster Identity (8.8). It is recommended to run the migration so your users and authorizations are transferred automatically. If you skip it, you’ll need to set up all authorizations manually in the new cluster.

When using the migration app, keep the following in mind:

It runs as a Kubernetes job.
It is idempotent, meaning you can safely rerun it without creating duplicates.
Both Keycloak and OIDC (e.g. Entra ID) are supported.
Migrates roles, groups, tenants, users, and their assignments.
if resource authorizations are used, you must enable the following to take your resource authorizations into account:

orchestration.migration.identity.resourceAuthorizationsEnabled: true

After a successful migration, you can delete the job, ConfigMap, and created migration client.

Keycloak

If you are using the internal Keycloak component that is provided by the Helm chart, the following entities will be migrated:

Roles and their permissions
Group relationships
Group members/users
Group role assignments (dependent on roles being migrated)
Group resource authorizations
User role assignments (dependent on roles being migrated)
Applications
Tenants (dependent on roles)

OIDC (OpenID Connect)

If you are using an external identity provider, such as Microsoft Entra ID, the following entities will be migrated:

Roles
Tenants
Mappings

Enable identity migration

Enable the identity migration in your values.yaml:

orchestration:
  migration:
    identity:
      enabled: true
      idpApplicationId: "your-id" # only required if you are using OIDC (OpenID Connect)

Recommended migration configuration

This example shows a full 8.8 values.yaml migration setup. While data migration and importers are required for a successful upgrade from 8.7, it’s recommended to enable all migration components:

orchestration:
  importer:
    enabled: true
  migration:
    identity:
      enabled: true
      idpApplicationId: "your-id" # only required if you are using OIDC (OpenID Connect)
      resourceAuthorizationsEnabled: true # only required if resource authorizations are used
    data:
      enabled: true

Prepare secrets for upgrade

This step is not required if your values.yaml already references Kubernetes secrets (not plaintext literals). In that case, no changes are needed - just ensure each secret.name points to the correct Kubernetes secret.

If you deployed Management Identity in 8.7 and either:

relied on the chart’s autogenerated secrets (including Keycloak), or
defined your secrets as inline values in values.yaml (plaintext literals),

then you must extract the current values, store them as Kubernetes Secrets, and reference them in your values.yaml to upgrade to 8.8 successfully (see guidance below).

note

“inline values (plaintext literals)” refers to secrets written directly as plaintext in your values.yaml, similar to Kubernetes --from-literal secrets. See the Kubernete secret documentation for details.

What you need to do

Extract current secret values from your 8.7 secrets.
Create a consolidated Kubernetes Secret (e.g., camunda-credentials).
Reference those keys in a values file used by 8.8.

The following is a working example - you can follow it as-is, or adapt it with your own secret names, manifests, or scripts.

caution

The list below shows secrets typically autogenerated by the Helm chart; the exact set depends on enabled components. For example, if you use an external Keycloak, remove the Keycloak-related items, etc.

Do not change or regenerate secrets during the upgrade. Reusing the same values preserves Identity and authentication data.

1. Extraction

NOTE: All Helm chart values mentioned here are based on the 8.7 syntax, as the upgrade has not happened yet.

# Change this according to your Helm chart release/deployment name and namespace.
RELEASE_NAME=camunda-dev
RELEASE_NAMESPACE=camunda-dev

# "global.identity.auth.enabled: true" is assumed for all "IDENTITY_*_CLIENT_SECRET" values.

# Only if "connectors.enabled: true".
export IDENTITY_CONNECTORS_CLIENT_SECRET=$(kubectl get secret "${RELEASE_NAME}-connectors-identity-secret" -o jsonpath="{.data.connectors-secret}" | base64 --decode)

# Only if "console.enabled: true".
export IDENTITY_CONSOLE_CLIENT_SECRET=$(kubectl get secret "${RELEASE_NAME}-console-identity-secret" -o jsonpath="{.data.console-secret}" | base64 --decode)

# Only if "optimize.enabled: true".
export IDENTITY_OPTIMIZE_CLIENT_SECRET=$(kubectl get secret "${RELEASE_NAME}-optimize-identity-secret" -o jsonpath="{.data.optimize-secret}" | base64 --decode)

# Only if "zeebe.enabled: true".
export IDENTITY_ZEEBE_CLIENT_SECRET=$(kubectl get secret "${RELEASE_NAME}-zeebe-identity-secret" -o jsonpath="{.data.zeebe-secret}" | base64 --decode)

# Only if "postgresql.enabled: true".
export WEB_MODELER_POSTGRESQL_ADMIN_SECRET=$(kubectl get secret "${RELEASE_NAME}-postgresql-web-modeler" -o jsonpath="{.data.postgres-password}" | base64 --decode)
export WEB_MODELER_POSTGRESQL_USER_SECRET=$(kubectl get secret "${RELEASE_NAME}-postgresql-web-modeler" -o jsonpath="{.data.password}" | base64 --decode)

# Only if "identityPostgresql.enabled: true".
export IDENTITY_POSTGRESQL_ADMIN_SECRET=$(kubectl get secret "${RELEASE_NAME}-identity-postgresql" -o jsonpath="{.data.postgres-password}" | base64 --decode)
export IDENTITY_POSTGRESQL_USER_SECRET=$(kubectl get secret "${RELEASE_NAME}-identity-postgresql" -o jsonpath="{.data.password}" | base64 --decode)

# Only if "identityKeycloak.enabled: true".
export KEYCLOAK_ADMIN_SECRET=$(kubectl get secret "${RELEASE_NAME}-keycloak" -o jsonpath="{.data.admin-password}" | base64 --decode)

# Only if "identityKeycloak.postgresql.enabled: true".
export KEYCLOAK_POSTGRESQL_ADMIN_SECRET=$(kubectl get secret "${RELEASE_NAME}-postgresql" -o jsonpath="{.data.postgres-password}" | base64 --decode)
export KEYCLOAK_POSTGRESQL_USER_SECRET=$(kubectl get secret "${RELEASE_NAME}-postgresql" -o jsonpath="{.data.password}" | base64 --decode)

2. Creation

Template a consolidated Secret manifest containing all keys you’ll reuse in 8.8:

cat << EOF >> existing-secrets-manifest.yaml
---
apiVersion: v1
kind: Secret
metadata:
  name: camunda-credentials
  namespace: "${RELEASE_NAMESPACE}"
type: Opaque
stringData:
  # Only if "connectors.enabled: true".
  identity-connectors-client-token: "${IDENTITY_CONNECTORS_CLIENT_SECRET}"

  # Only if "console.enabled: true".
  identity-console-client-token: "${IDENTITY_CONSOLE_CLIENT_SECRET}"

  # Only if "optimize.enabled: true".
  identity-optimize-client-token: "${IDENTITY_OPTIMIZE_CLIENT_SECRET}"

  # Only if "orchestration.enabled: true".
  identity-orchestration-client-token: "${IDENTITY_ZEEBE_CLIENT_SECRET}"

  # Only if "identityPostgresql.enabled: true".
  identity-postgresql-admin-password: "${IDENTITY_POSTGRESQL_ADMIN_SECRET}"
  identity-postgresql-user-password: "${IDENTITY_POSTGRESQL_USER_SECRET}"

  # Only if "keycloak.enabled: true".
  identity-keycloak-admin-password: "${KEYCLOAK_ADMIN_SECRET}"

  # Only if "keycloak.postgresql.enabled: true".
  identity-keycloak-postgresql-admin-password: "${KEYCLOAK_POSTGRESQL_ADMIN_SECRET}"
  identity-keycloak-postgresql-user-password: "${KEYCLOAK_POSTGRESQL_USER_SECRET}"

  # Only if "postgresql.enabled: true".
  webmodeler-postgresql-admin-password: "${WEB_MODELER_POSTGRESQL_ADMIN_SECRET}"
  webmodeler-postgresql-user-password: "${WEB_MODELER_POSTGRESQL_USER_SECRET}"
EOF

Inspect and apply:

Review existing-secrets-manifest.yaml and ensure it contains exactly the secrets for the components enabled in your 8.7 deployment.

kubectl apply -n "${RELEASE_NAMESPACE}" -f existing-secrets-manifest.yaml

3. Referencing

Reference the new Secret and keys in a values file for your 8.8 deployment. You can either update your 8.8 values.yaml or create a separate file (for example, existing-secrets-values.yaml) and include it during the Helm upgrade.

caution

If a component already uses its own existing secret, make sure to remove that section from the configuration to avoid overriding it.

# existing-secrets-values.yaml
global:
  identity:
    auth:
      console:
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-console-client-token"
      optimize:
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-optimize-client-token"

identityPostgresql:
  auth:
    existingSecret: "camunda-credentials"
    secretKeys:
      adminPasswordKey: "identity-postgresql-admin-password"
      userPasswordKey: "identity-postgresql-user-password"

identityKeycloak:
  auth:
    existingSecret: "camunda-credentials"
    passwordSecretKey: "identity-keycloak-admin-password"
  postgresql:
    auth:
      existingSecret: "camunda-credentials"
      secretKeys:
        adminPasswordKey: "identity-keycloak-postgresql-admin-password"
        userPasswordKey: "identity-keycloak-postgresql-user-password"

webModelerPostgresql:
  auth:
    existingSecret: "camunda-credentials"
    secretKeys:
      adminPasswordKey: "webmodeler-postgresql-admin-password"
      userPasswordKey: "webmodeler-postgresql-user-password"

connectors:
  security:
    authentication:
      oidc:
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-connectors-client-token"

orchestration:
  security:
    authentication:
      oidc:
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-orchestration-client-token"

Upgrade with Helm

After preparing your secrets and setting the migration configuration (data, identity migration, and importers), trigger the upgrade with helm upgrade.

If you extracted secrets into a separate file (e.g., existing-secrets-values.yaml), include it alongside your main values file:

helm repo update
helm upgrade camunda camunda/camunda-platform \
    -f values-8.8.yaml \
    -f existing-secrets-values.yaml

If your secrets are already referenced directly in your values-8.8.yaml, you can omit the extra file and just run:

helm repo update
helm upgrade camunda camunda/camunda-platform \
    -f values-8.8.yaml

Step 4: Monitor and validate

Monitor the upgrade

Monitor the Helm job logs (identity-migration, process-application-migration).

Validate the upgrade

Confirm the migration has finished by checking application logs and readiness status.

Troubleshooting

Upgrade failed due to missing secrets

The following upgrade error is related to secrets extraction:

Error: UPGRADE FAILED: execution error at (camunda-platform/charts/identity/templates/tasklist-secret.yaml:10:22):
PASSWORDS ERROR: You must provide your current passwords when upgrading the release.
                 Note that even after reinstallation, old credentials may be needed as they may be kept in persistent volume claims.
                 Further information can be obtained at https://docs.bitnami.com/general/how-to/troubleshoot-helm-chart-issues/#credential-errors-while-upgrading-chart-releases

    'global.identity.auth.tasklist.existingSecret' must not be empty, please add '--set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET' to the command. To get the current value:

        export TASKLIST_SECRET=$(kubectl get secret --namespace "camunda" "camunda-platform-test-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode)

When the Helm chart is removed or upgraded, persistent volume claims (PVCs) for secret storage are not removed or recreated. To prevent Helm from recreating secrets that have already been generated, the Bitnami library chart used by Camunda blocks the upgrade path, resulting in the above error.

To complete your upgrade, extract your secrets and provide them as environment variables during the upgrade process.

Prerequisites​

Recommended upgrade steps​

Step 1: Create 8.8 values.yaml​

Step 2: Update for 8.8 compatibility​

Overview of major changes​

Ensure required components​

Authentication​

Basic auth​

OIDC​

OAuth (Keycloak)​

LDAP​

Migrate secrets to new format​

Migrate to combined Ingress​

Multi-tenancy configuration​

Values key changes​

Renamed keys - update references directly​

Relocated keys - move under orchestration​

Merged keys - manually consolidate​

Step 3: Prepare and run the upgrade​

Enable importer (required)​

Data migration (required)​

Identity migration (optional)​

Keycloak​

OIDC (OpenID Connect)​

Enable identity migration​

Recommended migration configuration​

Prepare secrets for upgrade​

1. Extraction​

2. Creation​

3. Referencing​

Upgrade with Helm​

Step 4: Monitor and validate​

Monitor the upgrade​

Validate the upgrade​

Troubleshooting​

Upgrade failed due to missing secrets​

Prerequisites

Recommended upgrade steps

Step 1: Create 8.8 `values.yaml`

Step 2: Update for 8.8 compatibility

Overview of major changes

Ensure required components

Authentication

Basic auth

OIDC

OAuth (Keycloak)

LDAP

Migrate secrets to new format

Migrate to combined Ingress

Multi-tenancy configuration

Values key changes

Renamed keys - update references directly

Relocated keys - move under orchestration

Merged keys - manually consolidate

Step 3: Prepare and run the upgrade

Enable importer (required)

Data migration (required)

Identity migration (optional)

Keycloak

OIDC (OpenID Connect)

Enable identity migration

Recommended migration configuration

Prepare secrets for upgrade

1. Extraction

2. Creation

3. Referencing

Upgrade with Helm

Step 4: Monitor and validate

Monitor the upgrade

Validate the upgrade

Troubleshooting

Upgrade failed due to missing secrets