Skip to main content
Version: 8.8

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:

PrerequisiteDescription
Helm chart version and Helm CLI versionDetermine your Helm chart version and Helm CLI version and update them to the recommended versions listed in the version matrix.
Configuration changesEnsure all required configuration changes in this guide are reviewed, understood, and implemented before running the helm upgrade command.
8.7 values.yamlThe 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 managementThe 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.

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.yaml13.x/8.8 values.yaml
postgresqlRelocate to webModelerPostgresql
zeebeRelocate 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.audienceAdd 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.operateNeeds to be removed.
global.identity.auth.tasklist.audienceAdd 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.tasklistNeeds 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.enabledOperate is enabled by default and can be disabled via the new key. orchestration.profiles.operate: false
tasklist.enabledTasklist is enabled by default and can be disabled via the new key. orchestration.profiles.tasklist: false
zeebeGateway.ingress.grpcRelocate to orchestration.ingress.grpc
zeebeGateway.service.grpcPortRelocate to orchestration.service.grpcPort
zeebeGateway.service.commandPortRelocate to orchestration.service.commandPort
zeebeGateway.service.restPortRelocate to orchestration.service.httpPort
zeebeGateway.service.internalPortRelocate 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.contextPathThere is no dedicated Operate context path anymore it will be availabe on the following sub-path {contextPath}/operate defined by orchestration.contextPath.
tasklist.contextPathThere 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.enabledThere 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.contextPathThere 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
operatePlease revise whether any of the remaining config may be relevant for the new joint orchestration configuration before removing those completely.
tasklistPlease revise whether any of the remaining config may be relevant for the new joint orchestration configuration before removing those completely.
zeebeGatewayPlease 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.x13.x/8.8.x key to enable it
Consoleconsole.enabled: true
Management Identity
Management Identity PostgreSQL database
Management Identity Keycloak (Bitnami subchart)		identity.enabled: true
identityPostgresql.enabled: true
identityKeycloak.enabled: true
Optimizeoptimize.enabled: true
Web Modeler
Web Modeler PostgreSQL database		webModeler.enabled: true
identityPostgresql.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:

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.

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:

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

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

Expected log output:

  • Importer logs will show batches of records being imported and end with Importer finished successfully.
  • Data migration logs contain the following entries
  • Identity migration logs contain the following entries
  • Once both jobs report completion, they automatically terminate with status Complete.

If a job is stuck in Running or CrashLoopBackOff, inspect its logs. Wait until all pods are up and in ready state before continuing.

Validate the upgrade​

  1. Confirm all pods are healhy:
kubectl -n <namespace> get pods
  1. 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}"
  1. 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
  1. Verify workers

Verify yoru workers are still working

  1. Optional: Scale down importer

Scale down the importer once confirmed idle:

kubectl -n <namespace> scale deploy/<importer-name> --replicas=0

Troubleshooting​

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.