Camunda 8.4 to 8.5 Helm chart upgrade
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 10.2.0+
As of this Helm chart version, the image tags for all components are independent, and do not reference the global image tag. The value of the key global.image.tag
is null
, and each component now sets its own version.
With this change, Camunda applications no longer require a unified patch version. For example, a given installation may use Zeebe version 8.5.1, and Operate version 8.5.2. Note that only the patch version can differ between components.
Helm chart 10.0.2+
The upgrade path for Camunda Helm chart v9.x.x is to the latest patch version of v10.
- You can use any minor or patch version after (and including) 10.0.2.
- You cannot upgrade from v9.x.x to v10.0.0 or v10.0.1.
The Camunda Helm chart v10.0.2 has major changes in the values file structure. Follow the upgrade steps for each component before starting the chart upgrade.
Helm CLI version
Ensure to use Helm CLI with version 3.14.3
or more. The upgrade could fail to work with the 10.0.2+ Camunda Helm chart version due to some bugs in the older Helm CLI itself.
Deprecation notes
The following keys were deprecated in 8.5, and their removal has been delayed until the release of Camunda 8.7. We highly recommend updating the keys in your values file rather than waiting until the 8.7 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 |
Identity
The Camunda Identity component was formerly a sub-chart of the Camunda Helm chart. Now, it is part of the parent Camunda Helm chart.
There are no changes in the Identity keys, but since the LabelSelector
and MatchLabels
of a Kubernetes resource are immutable, its deployment should be deleted as the label app.kubernetes.io/name
has been changed from identity
to camunda-platform
.
- This step will lead to temporary downtime in Camunda 8 till the actual upgrade happens.
- This step doesn't affect any stored data and the deployment will be placed again in the upgrade.
kubectl -n camunda delete -l app.kubernetes.io/name=identity deployment
Identity - Keycloak
In Camunda Helm chart v10.0.0, the Identity Keycloak Helm chart has been upgraded from v17.3.6 to v19.4.1. Which has different defaults.
If, and only if, you make a full copy of the Camunda Helm chart values file instead of just overwriting the default value, you need to update your values files and use the new default values.
Namely, the following volumes should be removed from the values since they are now part of the upstream chart:
# Note: Since v10.0.0 the Keycloak "identity.keycloak" has been renamed to "identityKeycloak".
# Check the keys deprecation notes above.
identity:
keycloak:
extraVolumes:
- name: config
emptyDir: {}
- name: quarkus
emptyDir: {}
- name: tmp
emptyDir: {}
volumeMounts:
- mountPath: /opt/bitnami/keycloak/conf/
name: config
- mountPath: /opt/bitnami/keycloak/lib/quarkus
name: quarkus
- mountPath: /tmp
name: tmp
Elasticsearch
In Camunda Helm chart v10.0.0, the Elasticsearch Helm chart has been upgraded from v19.19.4 to v20.0.0. Which has different defaults.
If, and only if, you make a full copy of the Camunda Helm chart values file instead of just overwriting the default value, you need to update your values files and use the new default values.
Namely, the following volumes should be removed from the values since they are now part of the upstream chart:
elasticsearch:
extraVolumes:
- name: tmp
emptyDir: {}
- name: logs
emptyDir: {}
- name: config-dir
emptyDir: {}
extraVolumeMounts:
- mountPath: /tmp
name: tmp
- mountPath: /usr/share/elasticsearch/logs
name: logs
- mountPath: /usr/share/elasticsearch/config
name: config-dir
Enabling external Elasticsearch
In v10.0.0, it is possible to use external Elasticsearch. For more information on how to set up external Elasticsearch, refer to using existing Elasticsearch.
Enabling external OpenSearch
In v10.0.0, it is possible to use external OpenSearch. For more information on how to set up external OpenSearch, refer to using external OpenSearch.
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.
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.