Camunda 8.7 to 8.8 Helm chart upgrade

This guide describes the steps and requirements for upgrading from Camunda 8.7 to Camunda 8.8 by upgrading the Helm chart version from 12.x to 13.x.

note

When upgrading to a new version of the Camunda 8 Helm charts, upgrade sequentially from the latest patch version of the current release to the latest patch version of the next release.

For example, if the current Helm chart version is 12.x.x, and the latest next major version is 13.0.1, the recommended upgrade is to 13.0.1 (not 13.0.0).

Upgrading between minor versions of the Camunda Helm chart may require configuration changes. To upgrade between patch versions or when no configuration changes are required, see the helm upgrade instructions.

Review the Camunda 8 Helm chart version matrix to determine the application and Helm chart versions of your installation.

helm repo update
helm search repo camunda/camunda-platform --versions

This guide describes the steps and requirements for upgrading from Camunda 8.7 to Camunda 8.8 by upgrading the Helm chart.

Prerequisites

Before upgrading, review the following prerequisites:

• Determine your Helm chart version and Helm CLI version and update them to the recommended versions listed in our version matrix.
• Ensure you have implemented any required configuration changes specific to the version you are upgrading to before running the helm upgrade command.

To view available versions:

helm repo update
helm search repo camunda/camunda-platform --versions

Understand the architecture changes

Camunda 8.8 introduces architectural changes and a new default deployment approach. Carefully follow the documentation and steps:

• Applications consolidation where Zeebe, Zeebe Gateway, Operate, and Tasklist have been merged into one artifact/deployment named Orchestration Cluster.
• Basic auth + Orchestration Cluster only (via zeebe StatefulSet) is now the default.
  • The Orchestration Cluster StatefulSet is still named zeebe to avoid downtime.
  • By default, all apps except the Orchestration Cluster are disabled.
  • Retention per app is no longer supported.
• 8.7 importers remain part of 8.8 for data migration.
  • They run idle after finishing.
  • You may scale them down manually; they will be removed in 8.9.
• Adjust resources for the new Orchestration Cluster layout.
• A new Camunda Exporter is used.
• Two Helm jobs support migration:
  • identity-migration
  • process-application-migration
• Dedicated Elasticsearch/OpenSearch clusters per app are no longer supported.
• Application metrics have changed — consult the release notes.

note

During the upgrade, do not change your architecture, configuration, or authentication method. This is not supported.

Perform the upgrade

1. Configure your 8.8 Helm chart

You must update your values.yaml to align with the 8.8 changes.

1.1 Camunda Helm chart values file changes

Adjust your values.yaml based on the 8.8 changes.

• Multi-tenancy must be configured in two locations.
• TLS/self-signed certificates apply only in the Orchestration Cluster.
• Double-check any deprecated or renamed config 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 type 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
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

Merged keys - manually consolidate

These keys existed separately across components. They must now be combined under orchestration. Pay close attention, as most are free-form inputs.

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

tip

It's recommended to migrate to the new values structure using the new key orchestration, but it's possible to enable a compatibility layer in the Camunda Helm chart. That means the old structure from Camunda 8.7 (Helm chart 12.x.x) will work with Camunda 8.8 (Helm chart 13.x.x).

global:
  compatibility:
    orchestration:
      enabled: true

1.2 Camunda applications

Enable or disable the required Camunda components for your use case:

• Orchestration Cluster (enabled by default)
• Connectors
• Console
• Management Identity
• Web Modeler
• Optimize

1.2.1 Enable Operate and Tasklist importers

In 8.8, the Operate and Tasklist importers are disabled by default because they are not required for normal execution.
When upgrading from 8.7.x, you must enable them to process any remaining data so that the upgrade can complete successfully.

To enable the importers, set:

• camunda.operate.importerEnabled=true
• camunda.tasklist.importerEnabled=true

1.3 Authentication

Depending on your authentication setup, you may need to run the Identity Migration App to migrate users, groups, roles, and tenants to the new Orchestration Cluster's Elasticsearch index.

Configure and start the app using the provided Helm job settings (e.g., identity-migration.enabled: true).

Make sure authentication is configured as guided:

1.3.1 Basic auth

• Previously used only in Operate/Tasklist.
• Now used for the entire Orchestration Cluster.
• Either migrate your users to the new cluster or reconfigure them.
• Zeebe authentication must be explicitly disabled, or users must be added to requests.

note

Zeebe had no authentication in 8.7. This must now be explicitly configured or disabled.

1.3.2 OIDC

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

1.3.3 OAuth (Keycloak)

Ensure your values.yaml matches the OAuth configuration guide.

1.3.4 LDAP

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

2. Perform a backup

Take a full backup before starting the upgrade process. Follow the Backup and Restore guide.

3. Identity migration

The Identity Migration app allows you to migrate data from Management Identity to the Orchestration Cluster Identity.
The migration maps your current authorization setup in Management Identity to the new authorization setup within the Orchestration Cluster Identity. If you prefer to set up your authorizations from scratch within the cluster, you can opt out of this migration.

Consider the following points before attempting the migration:

• The app is run as a Kubernetes job.
• It is available as a standalone migration app for Identity only. It runs separately from the cluster and the process migration.
• The Identity migration is idempotent, meaning no additional measures are needed to prevent duplicate entities if the migration is rerun.
• On any unhandled error while fetching data or creating an entity in the Orchestration Cluster, the app emits logs with clear error details.
  For example:
  Failed to retrieve groups from <URL>: StatusCode: <code>, Body: <response body>.
  It also logs a clear message indicating that the migration failed and must be retried once the error has been addressed. The application will terminate with an exit code.
• There is no tracking of migration progress. If the migration is rerun, it will re-perform all operations.
• The migration does not implement any retry behavior, except in response to backpressure from the Orchestration Cluster.

You can enable the migration by modifying the following value:

orchestration.migration.identity.enabled: true

This will create a job and a ConfigMap to configure the job.

Also, with this configuration, Management Identity will automatically configure a migration client via environment variables in the Identity deployment. This migration client will have read-only permissions to the Identity Resource Server and will communicate directly with the Zeebe brokers in the Orchestration Cluster.

The Identity Migration app supports two migration scenarios:

1. Keycloak
2. OIDC

3.1.1 Keycloak

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

1. Roles and their permissions
2. Group relationships
3. Group members/users
4. Group role assignments (dependent on roles being migrated)
5. Group resource authorizations
6. User role assignments (dependent on roles being migrated)
7. Applications
8. Tenants (dependent on roles)

Once the migration has completed successfully, you can safely delete the job, its associated ConfigMap, and the migration client in Management Identity.

3.1.2 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

Once the migration has completed successfully, you can safely delete the job, its associated ConfigMap, and the migration client in Management Identity.

4. Process migration

The process migration application upgrades process data storage from the old, separate indices used in Camunda 8.7 to the new unified index introduced in Camunda 8.8.

In 8.7 and earlier versions, there were two indices:

• tasklist-process
• operate-process

From 8.8 onward, there is a single operate-process index for the needs of the entire Camunda cluster.

warning

• Process migration cannot be run on a fresh install of 8.8. It is only supported when upgrading from 8.7.
• The migration can only run once.
• Before upgrading, ensure the 8.7 Zeebe workers have already processed some data. If there is no process data to migrate, the migration job will wait for the importers until the default timeout is reached, and the migration will fail.

To enable process migration, modify the following value:

orchestration:
  migration:
    process:
      enabled: true

By default, the Tasklist and Operate importers are disabled in 8.8. When the above value is set to true, the Tasklist and Operate importers are enabled. This is necessary because the migration will wait for the importers to stop processing data. If the importers are not running, the migration will not complete successfully.

A Kubernetes job is created to start the migration. This job can run for an extended period if needed, waiting for the importers to finish processing.

To confirm a successful migration, monitor the job logs and health status. For process migration specifically, Prometheus metrics are exposed. One useful metric is:

• camunda_migration_processes_migrated — should eventually match the number of documents in the operate-process index. This indicates the migration has completed successfully, even if other migration processes are still ongoing.

5. Run the upgrade

If you have installed the Camunda 8 Helm charts before with default values, Identity and the related authentication mechanism are enabled. If you have disabled Identity, see how to upgrade Camunda with Identity disabled.

Identity enabled

Extract secrets

If not specified on installation, the Helm chart generates random secrets for all components (including Keycloak). To upgrade successfully, these secrets must be extracted and provided during your upgrade.

To extract the secrets, use the following code snippet, replacing camunda with your actual Helm release name:

# Uncomment if Console is enabled.
# export CONSOLE_SECRET=$(kubectl get secret "camunda-console-identity-secret" -o jsonpath="{.data.console-secret}" | base64 --decode)
export TASKLIST_SECRET=$(kubectl get secret "camunda-tasklist-identity-secret" -o jsonpath="{.data.tasklist-secret}" | base64 --decode)
export OPTIMIZE_SECRET=$(kubectl get secret "camunda-optimize-identity-secret" -o jsonpath="{.data.optimize-secret}" | base64 --decode)
export OPERATE_SECRET=$(kubectl get secret "camunda-operate-identity-secret" -o jsonpath="{.data.operate-secret}" | base64 --decode)
export CONNECTORS_SECRET=$(kubectl get secret "camunda-connectors-identity-secret" -o jsonpath="{.data.connectors-secret}" | base64 --decode)
export ZEEBE_SECRET=$(kubectl get secret "camunda-zeebe-identity-secret" -o jsonpath="{.data.zeebe-secret}" | base64 --decode)
export KEYCLOAK_ADMIN_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.admin-password}" | base64 --decode)
export KEYCLOAK_MANAGEMENT_SECRET=$(kubectl get secret "camunda-keycloak" -o jsonpath="{.data.management-password}" | base64 --decode)
export POSTGRESQL_SECRET=$(kubectl get secret "camunda-postgresql" -o jsonpath="{.data.postgres-password}" | base64 --decode)

Run helm upgrade

After exporting all secrets into environment variables, run the following upgrade command:

helm repo update
helm upgrade camunda camunda/camunda-platform \
  # Uncomment if Console is enabled.
  # --set global.identity.auth.console.existingSecret=$CONSOLE_SECRET \
  --set global.identity.auth.tasklist.existingSecret=$TASKLIST_SECRET \
  --set global.identity.auth.optimize.existingSecret=$OPTIMIZE_SECRET \
  --set global.identity.auth.operate.existingSecret=$OPERATE_SECRET \
  --set global.identity.auth.connectors.existingSecret=$CONNECTORS_SECRET \
  --set global.identity.auth.zeebe.existingSecret=$ZEEBE_SECRET \
  --set identityKeycloak.auth.adminPassword=$KEYCLOAK_ADMIN_SECRET \
  --set identityKeycloak.auth.managementPassword=$KEYCLOAK_MANAGEMENT_SECRET \
  --set identityKeycloak.postgresql.auth.password=$POSTGRESQL_SECRET

If you have set secret values on installation, you must specify them again on the upgrade either via --set, as demonstrated above, or by passing in a values file using the -f flag.

note

For more details on the Keycloak upgrade path, see the Keycloak upgrade guide.

Identity disabled

If you have disabled Camunda Identity and the related authentication mechanism, Camunda can be upgraded with the following command:

helm repo update
helm upgrade camunda

6. Monitor the migration

• Monitor the Helm job logs (identity-migration, process-application-migration).
• 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.