Skip to main content
Version: 8.9 (unreleased)

Camunda 8.8 to 8.8 Helm chart upgrade

Upgrade from Camunda 8.8 to Camunda 8.9 by upgrading the Helm chart version from 13.x to 14.x.

Upgrade sequentially

Always upgrade from the latest patch of your current release to the latest patch of the next release. Example: from 13.x.x → 14.0.1 (not 14.0.0).

Prerequisites​

The following prerequisites are required before upgrading:

PrerequisiteDescription
Helm chart version and Helm CLI versionDetermine your Helm chart version and Helm CLI version and update them to the recommended versions listed in the version matrix.
Configuration changesEnsure all required configuration changes in this guide are reviewed, understood, and implemented before running the helm upgrade command.
8.8 values.yamlThe approach described in this guide uses your existing 8.8 values.yaml file as a basis to create a new 8.9 values.yaml.
Secret managementThe approach described in this guide is based on the assumption that all your secrets are referenced in an existing Kubernetes secret. See Extract plaintext values and reference them as Kubernetes Secrets for further guidance.
Maintenance windowPlan a short downtime window for the upgrade. The former Operate, Tasklist, and Zeebe Gateway deployments are replaced by the new Orchestration Cluster, which becomes available once the zeebe StatefulSet rollout completes.

The recommended approach is as follows:

  1. Create 8.9 values.yaml: Copy your existing 8.8 values.yaml and use it as the basis for the new 8.8 file.
  2. Update for 8.9 compatibility: Adjust the new values.yaml to match the changes in 8.9 and its updated architecture.
  3. Prepare and run the upgrade: Add the required upgrade-specific configuration and steps, then execute the helm upgrade command.
  4. Monitor and validate: Track the upgrade process and ensure all components start and function properly.
caution

During the upgrade, you must keep the same overall deployment setup. Configuration values must be updated where required for 8.9 compatibility, but architectural changes or switching authentication methods are not supported during the upgrade. For example, the same components should remain deployed, the same database connections used, and your authentication method must stay the same.

Step 1: Create 8.9 values.yaml​

Copy your existing 8.8 values.yaml, rename it (for example, values-8.9.yaml), and use it as the basis for your 8.9 configuration.

Step 2: Update for 8.9 compatibility​

Go through the following sections and configure your new 8.9 values.yaml file to be compatible with the new 8.9 changes and architecture.

Key 8.9 changes

Review What’s new in Camunda 8.8
and Assess Camunda 8.8 changes and impact before proceeding with your upgrade from 8.8.

Values key changes​

Adjust your values.yaml for the 8.9 configuration changes, and double-check for any deprecated or renamed values, we recommend the order as defined by the following keys:

13.x/8.8 values.yaml14.x/8.9 values.yaml
TBD

Other changes (TBD)​

Step 3: Prepare and run the upgrade​

Add required upgrade-specific configuration.

TDB

Upgrade with Helm​

After preparing your secrets and setting the migration configuratio, trigger the upgrade with helm upgrade:

helm repo update
helm upgrade camunda camunda/camunda-platform -f values-8.8.yaml

Step 4: Monitor and validate​

Monitor the upgrade​

After triggering the Helm upgrade, monitor the rollout to ensure all pods return to a healthy state and the migration jobs finish successfully.

1. Watch pod rollout progress​

Watch the pods being migrated via:

kubectl -n <namespace> get pods -w

What you should see:

  • Pods gradually terminate and restart with new versions.

Validate the upgrade​

  1. Confirm all pods are healhy:
kubectl -n <namespace> get pods
  1. Confirm all pods are running on the new 8.9.x images:
kubectl -n <namespace> get pods -o jsonpath="{range .items[*]}{.metadata.name}{':\t'}{range .spec.containers[*]}{.image}{'\n'}{end}{end}"
  1. Verify access to Camunda components
  • Acess Camunda components and verify users can log in with migrated roles. E.g. for the Orchestration cluster access:
https://<your-domain>/<contextPath>/operate
https://<your-domain>/<contextPath>/tasklist
https://<your-domain>/<contextPath>/identity
  1. Verify workers

If you’re running external workers for Camunda processes, ensure they are still connected and actively processing tasks after the migration.

Troubleshooting​

Upgrade failed due to missing secrets​

The following upgrade error might be related to not having secrets as Kubernetes referenced secrets as required in Prerequisites.

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 plaintext values and reference them as Kubernetes Secrets.