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, we recommend updating to the latest patch release of the next major version of the chart.

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:

note

When upgrading to a new version of the Camunda 8 Helm charts, we recommend updating to the latest patch release of the next major version of the chart.

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

• 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

Upgrade

1. Understand 8.8 architecture changes
2. Configure your 8.8 Helm chart
3. Perform a backup
4. Run the upgrade
5. Monitor the migration

1. Understand the 8.8 architecture changes

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

• 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

Do not change your architecture, configuration, or authentication method during the upgrade. This is not supported.

2. Configure your 8.8 Helm chart

Update your values.yaml with all required configuration changes.

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

Component	Old Key	New Key	Default Value
Web Modeler
	postgresql	webModelerPostgresql	N/A

2.2 C8 applications

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

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

2.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:

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

2.3.2 OIDC

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

2.3.3 OAuth (Keycloak)

Ensure your values.yaml matches the OAuth configuration guide.

2.3.4 LDAP

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

3. Perform a backup

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

4. 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:

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

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

4.1.2 OIDC

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.

5. 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:

core:
  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.

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

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