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).

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.
Secret management	The approach described in this guide is based on the assumption that all your secrets are referenced in an existing Kubernetes secret. See Extract plaintext values and reference them as Kubernetes Secrets for further guidance.
Maintenance window	Plan a short downtime window for the upgrade. The former Operate, Tasklist, and Zeebe Gateway deployments are replaced by the new Orchestration Cluster, which becomes available once the zeebe StatefulSet rollout completes.

Recommended upgrade steps

The recommended approach is as follows:

1. Create 8.8 values.yaml: Copy your existing 8.7 values.yaml and use it as the basis for the new 8.8 file.
2. Update for 8.8 compatibility: Adjust the new values.yaml to match the changes in 8.8 and its updated architecture.
3. Prepare and run the upgrade: Add the required upgrade-specific configuration and steps, then execute the helm upgrade command.
4. 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.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.

Values key changes

Adjust your values.yaml for the 8.8 configuration changes, and double-check for any deprecated or renamed values, we recommend the order as defined by the following keys:

12.x/8.7 values.yaml	13.x/8.8 values.yaml
postgresql	Relocate to webModelerPostgresql
zeebe	Relocate to orchestration and use as a base for the new Orchestration Cluster Configuration. Note: You may consider increasing the orchestration.resources here, given the orchestration component will now include and serve all Orchestration Cluster components by default. Note: the type of clusterSize, partitionCount and replicationFactor changed from int to string.
Global Identity keys
global.identity.auth.connectors.*	Relocate to connectors.security.authentication.oidc.* and set connectors.security.authentication.method: oidc
global.identity.auth.zeebe.*	Relocate to orchestration.security.authentication.oidc.*
global.identity.auth.operate.audience	Add the audience value to the list of orchestration.security.authentication.oidc. backwardsCompatibleAudiences if you want to keep clients for this audience operational and allow them to access the Orchestration Cluster API.
global.identity.auth.operate	Needs to be removed.
global.identity.auth.tasklist.audience	Add the audience value to the list of orchestration.security.authentication.oidc. backwardsCompatibleAudiences if you want to keep clients for this audience operational and allow them to access the Orchestration Cluster API.
global.identity.auth.tasklist	Needs to be removed.
Connectors keys to relocate
connectors.env[i].name=OPERATE_CLIENT_SCOPE connectors.env[i].value={scope}	There is now a dedicated key to configure the client scope connectors.security.authentication.oidc.tokenScope: {scope}
Cluster component keys to relocate
operate.enabled	Operate is enabled by default and can be disabled via the new key. orchestration.profiles.operate: false
tasklist.enabled	Tasklist is enabled by default and can be disabled via the new key. orchestration.profiles.tasklist: false
zeebeGateway.ingress.grpc	Relocate to orchestration.ingress.grpc
zeebeGateway.service.grpcPort	Relocate to orchestration.service.grpcPort
zeebeGateway.service.commandPort	Relocate to orchestration.service.commandPort
zeebeGateway.service.restPort	Relocate to orchestration.service.httpPort
zeebeGateway.service.internalPort	Relocate to orchestration.service.internalPort
Cluster component keys to merge
operate.configuration tasklist.configuration zeebeGateway.configuration	All former Operate, Tasklist and Zeebe Gateway configuration need to get merged into orchestration.configuration. Please note that some legacy application properties got deprecated and replaced with unified Orchestration Cluster Configuration see Camunda 8.8 property changes for more details.
operate.env tasklist.env zeebeGateway.env	All former Operate, Tasklist and Zeebe Gateway Environment Variables need to get merged into orchestration.env Please note that some legacy application environment variables got deprecated and replaced with unified Orchestration Cluster Configuration see Camunda 8.8 property changes for more details.
operate.envFrom tasklist.envFrom zeebeGateway.envFrom	All former Operate, Tasklist and Zeebe Gateway Environment Variables need to get merged into orchestration.envFrom Please note that some legacy application environment variables got deprecated and replaced with unified Orchestration Cluster Configuration see Camunda 8.8 property changes for more details.
operate.extraConfiguration tasklist.extraConfiguration zeebeGateway.extraConfiguration	All former Operate, Tasklist and Zeebe extraConfiguration needs to get merged into orchestration.extraConfiguration
operate.initContainers tasklist.initContainers zeebeGateway.initContainers	All former Operate, Tasklist and Zeebe initContainers need consideration to get merged into orchestration.initContainers
operate.retention tasklist.retention	Former Operate and Tasklist retention configurations needs to get merged into orchestration.history.retention. In Camunda 8.8, historical data retention is unified across Operate, Tasklist, and Camunda indices under a single configuration. For detailed configuration guidance, see Configure data retention.
operate.sidecars tasklist.sidecars zeebeGateway.sidecars	All former Operate, Tasklist and Zeebe sidecars need consideration to get merged into orchestration.sidecars
operate.extraVolumeMounts tasklist.extraVolumeMounts zeebeGateway.extraVolumeMounts	All former Operate, Tasklist and Zeebe extraVolumes need consideration to get merged into orchestration.extraVolumeMounts
operate.extraVolumes tasklist.extraVolumes zeebeGateway.extraVolumes	All former Operate, Tasklist and Zeebe extraVolumes need consideration to get merged into orchestration.extraVolumes
Replaced deprecated component specific keys with no equivalent
operate.contextPath	There is no dedicated Operate context path anymore it will be availabe on the following sub-path {contextPath}/operate defined by orchestration.contextPath.
tasklist.contextPath	There is no dedicated Operate context path anymore it will be availabe on the following sub-path {contextPath}/tasklist defined by orchestration.contextPath.
tasklist.identity.userAccessRestrictions.enabled	There is no equivalent key in the 13.x Helm chart, you would need to actively switch to the Tasklist V1 API through orchestration.{env,envFrom,configuration}, see Switching between Tasklist V1 and V2 modes for the relevant configuration properties.
zeebeGateway.contextPath	There is no dedicated Zeebe Gateway context path anymore, orchestration.contextPath defines the context path for the Orchstration Cluster, the Orchestration Cluster API will be available under {contextPath}/v2
Removal of remaining component specific keys
operate	Please revise whether any of the remaining config may be relevant for the new joint orchestration configuration before removing those completely.
tasklist	Please revise whether any of the remaining config may be relevant for the new joint orchestration configuration before removing those completely.
zeebeGateway	Please revise whether any of the remaining config may be relevant for the new joint orchestration configuration before removing those completely.

Changes to the default deployment setup

Starting with Camunda 8.8, the set of components deployed by default has changed compared to 8.7.
If you used any of the components listed below, you must now enable them explicitly to ensure they are present after the upgrade.

Component disabled by default with 13.x/8.8.x	13.x/8.8.x key to enable it
Console	console.enabled: true
Management Identity Management Identity PostgreSQL database Management Identity Keycloak (Bitnami subchart)	identity.enabled: true identityPostgresql.enabled: true identityKeycloak.enabled: true
Optimize	optimize.enabled: true
Web Modeler Web Modeler PostgreSQL database	webModeler.enabled: true webModelerPostgresql.enabled: true

For more information, see Enable additional components.

Multi-tenancy configuration

If you previously configured Multi-tenancy in 8.7, note that it now requires additional configuration for the Orchestration Cluster (orchestration.*). For guidance, see Configure multi-tenancy in the Helm chart.

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.

Authentication

Make sure authentication is configured according to the following guidance:

OIDC

For your OIDC configuration, make sure at least the following keys are set, this is an example for Microsoft Entra ID:

global:
  security:
    authentication:
      method: oidc
orchestration:
  security:
    authentication:
      oidc:
        # :start: relocated from former `global.identity.auth.zeebe`
        clientId: <YOUR_CLIENTID>
        secret:
          existingSecret: <YOUR_CLIENTSECRET>
          existingSecretKey: <YOUR_CLIENTSECRET_KEY>
        audience: <YOUR_AUDIENCE>
        # :end: relocated from former `global.identity.auth.zeebe`
        redirectUrl: https://<YOUR_PUBLIC_HOST>{{ .Values.orchestration.contextPath }}
        # Configure the claim in the access token to identify a client, default: client_id
        clientIdClaim: azp
        # Configure the claim in the access token to identify a user by, default: preferred_username
        usernameClaim: preferred_username
        # Configure the claim in the access token to retrieve groups from, default: groups
        groupsClaim: groups
        # For Microsoft Entra ID the following scopes are required
        scope:
          - openid
          - profile
          - offline_access
          - <YOUR_AUDIENCE>/.default
        # In case of Microsoft Entra ID, a user acces token contains `azp` and `preferred_username` thus the username claim needs to be preferred
        preferUsernameClaim: true

OAuth with Keycloak

Internal Keycloak

global:
  security:
    authentication:
      method: oidc
orchestration:
  security:
    authentication:
      method: oidc
      oidc:
        secret:
          existingSecret: <YOUR_CLIENTSECRET>
          existingSecretKey: <YOUR_CLIENTSECRET_KEY>
  redirectUrl: https://<YOUR_PUBLIC_HOST>{{ .Values.orchestration.contextPath }}

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

warning

In the Camunda 8.7 Helm chart, Keycloak has been upgraded to version 26.3.3, which introduces changes to environment variable prefixes.
Some variables previously using the KEYCLOAK_ prefix now use KC_.

For details, see the Keycloak release notes.

Update the prefix for any affected environment variables in your configuration. No action is required if you don’t use custom variables passed to the Keycloak deployment (for example, via the values file or post-rendering).

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.

LDAP

LDAP authentication is not supported in the new 8.8 architecture. Contact Camunda Consulting for assistance with LDAP authentication requirements.

Step 3: Prepare and run the upgrade

Add required upgrade-specific configuration.

Data migration

For the migration, you must enable the data migration configuration. See Data migration for details:

orchestration:
  migration:
    data:
      enabled: true

Identity migration

It is recommended to enable the identity migration to automatically migrate your permissions setup from Management Identity into the Orchestration cluster Identity, preserving your existing authorization setup from 8.7. For further insights, see Running the Identity Migration Application:

OIDC

The Identity Migration App requires read access to Management Identity.

You thus either need to create or reuse existing client credentials with the read permission for the Management Identity API and provide the corresponding clientId and secret for it.

1. Create a file named identity-migration-secret.yaml with the following content:

apiVersion: v1
kind: Secret
metadata:
  name: identity-migration-secret
type: Opaque
data:
  password: "WU9VUl9QQVNTV09SRA==" # base64 encoded YOUR_PASSWORD

2. Apply the secret to your cluster:

kubectl apply -f identity-migration-secret.yaml

Reference this secret in your values-8.8.yaml file and enable the identity migration app. You can rely on an automatically created Mapping Rule for that client by providing a claimName and claimValue to authorize the client for the Management Identity API.

orchestration:
  migration:
    identity:
      enabled: true
      # In case of Microsoft Entra ID, you can use the `azp` claim that contains the client_id value
      claimName: azp
      claimValue: <YOUR_IDENTITY_CLIENT_ID>
      clientId: <YOUR_IDENTITY_CLIENT_ID>
      secret:
        existingSecret: identity-migration-secret
        existingSecretKey: password

OAuth with Keycloak

To authorize the Identity Migration App with your Keycloak instance, you need to create a new Kubernetes Secret.

1. Create a file named identity-migration-secret.yaml with the following content:

apiVersion: v1
kind: Secret
metadata:
  name: identity-migration-secret
type: Opaque
data:
  password: "WU9VUl9QQVNTV09SRA==" # base64 encoded YOUR_PASSWORD

2. Apply the secret to your cluster:

kubectl apply -f identity-migration-secret.yaml

Reference this secret in your values-8.8.yaml file and enable the identity migration app:

info

The Helm chart creates a dedicated Keycloak client with read-only access to your Identity Resource Server. If you override your Identity clients, follow the Helm chart section in Common configuration for the Identity Migration application to set up the required migration client.

migration:
  identity:
    enabled: true
    secret:
      existingSecret: identity-migration-secret
      existingSecretKey: password
    # Only required if resource authorizations are used
    resourceAuthorizationsEnabled: true

Upgrade with Helm

caution

If custom prefixes are used for the Camunda indices, make sure to perform the Prefix migration before proceeding.

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

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

Step 4: Monitor and validate

Monitor the upgrade

After triggering the Helm upgrade, monitor the rollout to ensure all pods return to a healthy state and the migration jobs finish successfully.

1. Watch pod rollout progress

Watch the pods being migrated via:

kubectl -n <namespace> get pods -w

What you should see:

• Pods gradually terminate and restart with new versions.
• The Orchestration Cluster (zeebe StatefulSet) retains its name to prevent downtime - previous Operate and Tasklist pods will terminate.
• A *-importer deployment handles remaining 8.7 records.
• If both migrations are enabled, two Kubernetes Jobs run in parallel:
  • *-zeebe-migration-data (always present)
  • *-zeebe-migration-identity (optional – only if identity migration is enabled)

2. Inspect migration and importer logs

# Importer deployment (migrates remaining Zeebe data)
kubectl -n <namespace> logs deploy/<importer-name> -f

# Data migration job
kubectl -n <namespace> logs job/<release>-zeebe-migration-data -f

# Identity migration job (if enabled)
kubectl -n <namespace> logs job/<release>-zeebe-migration-identity -f

If a job is stuck in Running or CrashLoopBackOff, inspect its logs. Wait until all pods are up and in ready state before continuing. If the job stops retrying, see Migration job did not complete.

Validate the upgrade

1. Confirm all pods are healhy:

kubectl -n <namespace> get pods

2. Confirm all pods are running on the new 8.8.x images:

kubectl -n <namespace> get pods -o jsonpath="{range .items[*]}{.metadata.name}{':\t'}{range .spec.containers[*]}{.image}{'\n'}{end}{end}"

3. Verify access to Camunda components

• Acess Camunda components and verify users can log in with migrated roles. E.g. for the Orchestration cluster access:

https://<your-domain>/<contextPath>/operate
https://<your-domain>/<contextPath>/tasklist
https://<your-domain>/<contextPath>/identity

4. Verify workers

If you’re running external workers for Camunda processes, ensure they are still connected and actively processing tasks after the migration.

Troubleshooting

Migration job did not complete

If the migration job (for data or identity) fails to complete and eventually stops retrying, it likely hit its backoffLimit (the maximum number of retry attempts). This usually happens when the importer job wasn’t finsihing yet before the jobs stops.

How to fix this:

1. Check the job status

kubectl -n <namespace> get jobs

2. Delete the failed migration jobs

kubectl -n <namespace> delete job camunda-zeebe-migration-data
kubectl -n <namespace> delete job camunda-zeebe-migration-identity

3. Rerun your Helm upgrade command to recreate and restart the migration jobs:

Upgrade failed due to missing secrets

The following upgrade error might be related to not having secrets as Kubernetes referenced secrets as required in Prerequisites.

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 plaintext values and reference them as Kubernetes Secrets.