Camunda 8.5 to 8.6 Helm chart upgrade

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 10.x.x, and the latest next major version is 11.0.1, the recommended upgrade is to 11.0.1 (not 11.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.

Upgrade requirements

For a smooth upgrade experience, we recommend determining both your Helm chart and Helm CLI versions prior to starting your upgrade.

Helm chart version

As of the Camunda 8.4 release, the Camunda 8 Helm chart version is independent from the application version (for example, the Camunda 8.4 release uses the Helm chart version 9.0.0). The Helm chart is updated with each application release.

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

You can also view all chart versions and application versions via the Helm CLI:

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

Helm CLI version

Use the recommended Helm CLI version for your Helm chart when upgrading. The Helm CLI version for each chart can be found on the chart version matrix.

Update your configuration

Configuration adjustments may be required when upgrading to a new version of the Helm chart. Before beginning your upgrade, ensure you have implemented any changes required by your new version.

Helm chart 11.0.0+

Deprecation notes

The following keys were deprecated in 8.5, and their removal has been delayed until the release of Camunda 8.8. We highly recommend updating the keys in your values file rather than waiting until the 8.8 release.

Component	Old Key	New Key
Identity
	identity.keycloak	identityKeycloak
	identity.postgresql	identityPostgresql
Zeebe Gateway
	global.zeebePort	zeebeGateway.service.grpcPort
	zeebe-gateway	zeebeGateway
	zeebeGateway.service.gatewayName	zeebeGateway.service.grpcName
	zeebeGateway.service.gatewayPort	zeebeGateway.service.grpcPort
	zeebeGateway.ingress	zeebeGateway.ingress.grpc
	-	zeebeGateway.ingress.rest
Elasticsearch
	global.elasticsearch.url	Change from a string to a map
	global.elasticsearch.protocol	global.elasticsearch.url.protocol
	global.elasticsearch.host	global.elasticsearch.url.host
	global.elasticsearch.port	global.elasticsearch.url.port

Component	Old Key	New Key
Web Modeler
	postgresql	webModelerPostgresql

Separated Ingress deprecation warning

The separated Ingress Helm configuration has been deprecated in 8.6, and will be removed from the Helm chart in 8.8. If using a separated Ingress, switch to a combined Ingress to ensure a smooth upgrade experience.

OpenShift Changes

We added the global.compatibility.openshift.adaptSecurityContext variable in the values.yaml that can be used to set the following possible values:

• force: The runAsUser and fsGroup values will be null in all components.
• disabled: The runAsUser and fsGroup values will not be modified (default).

With this change, there is no need to do extra steps with the post-renderer. You can install the chart as normal. Please refer to the Red Hat OpenShift document for more information.

New base path for Operate and Tasklist web applications

We have introduced a new base path for both the Operate and Tasklist web applications. The new base path for Operate is /operate, and for Tasklist, it is /tasklist. For more information, see the 8.6 announcements.

Upgrade Camunda

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

Upgrade failed

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 nor 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, then provide them as environment variables during the upgrade process.