Camunda 8 Helm 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.
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:
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
- Understand 8.8 architecture changes
- Configure your 8.8 Helm chart
- Perform a backup
- Run the upgrade
- 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.
- The orchestration cluster StatefulSet is still named
- 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.
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.
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: true
This will create a job and a ConfigMap to configure the job.
The Identity Migration app supports two authentication scenarios:
- Keycloak
- OIDC
4.1.1 Keycloak
When Identity migration is enabled through the values.yaml
, Management Identity will automatically configure a migration client via environment variables. 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 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)
Once the migration is complete, you can safely delete the job, its associated ConfigMap, and the migration client in Management Identity.
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.
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.