Skip to main content
Version: 8.9 (unreleased)

Upgrade Camunda 8.8 to 8.9 using Helm

Upgrade a Helm-managed Camunda 8 Self-Managed deployment from version 8.8 to 8.9.

Prerequisites​

Before upgrading, check you have met the following prerequisites:

PrerequisiteDescription
Confirm latest 8.8.x patchConfirm your deployment is running the latest 8.8.x patch. If you are upgrading from a version earlier than 8.8, see Upgrading from an earlier version.
Confirm upgrade eligibilityReview Prepare for upgrade to confirm upgrade eligibility and complete any required pre-upgrade actions for 8.9.
Confirm Helm chart support

Review the Camunda Helm chart version matrix and confirm:

  • The Helm chart version deploying 8.9 is supported for your Kubernetes version.
  • Your Helm client version is supported for that chart.

BackupsCreate and verify backups for your Camunda data. See Backup and restore.
Check your values.yamlReview your existing values.yaml for deprecated secret keys that must be migrated, and for any Elasticsearch, Ingress, or authentication settings that may need updating.
Migrate deprecated secret keysIf your values.yaml still uses deprecated secret keys from 8.8 (for example, global.license.key, *.existingSecret at the old paths), migrate them to the new *.secret.existingSecret pattern. See Configuration changes below.
Set secondary storage typeCamunda 8.9 no longer defaults to Elasticsearch. Explicitly setting orchestration.data.secondaryStorage.type is recommended. See Secondary storage type.
Test upgradeTest the upgrade in a non-production environment using a copy of your production configuration.

Create your 8.9 values file​

Use your existing 8.8 configuration as the starting point for the upgrade.

  1. Copy your current values.yaml and name the file values-8.9.yaml.

  2. Download the default values for the Camunda 8.9 Helm chart:

    helm repo update
    helm show values camunda/camunda-platform --version <CHART_VERSION> > values-8.9-default.yaml

    To identify the latest available chart version, run:

    helm search repo camunda/camunda-platform --versions

  3. Compare values-8.9.yaml with values-8.9-default.yaml to identify:

    • new configuration options,
    • changed defaults, and
    • deprecated or removed settings.

  4. Update values-8.9.yaml using the configuration tables below before running helm upgrade.

Update your values file to 8.9​

Use the following sections to update values-8.9.yaml for the 8.8 to 8.9 upgrade.

Configuration changes​

The following sections list configuration keys that changed between chart 13.x (8.8) and 14.x (8.9). If your values.yaml uses any of these keys, update them before upgrading.

Deprecated secret keys removed​

Secret configuration keys that were deprecated in 8.8 are removed in 8.9. If your values.yaml still references any of the old paths, update them to use the new *.secret.* pattern.

For the full list of affected keys, see Helm chart: Deprecated secret keys removed.

The following table summarizes the pattern change by component:

Component13.x/8.8 key pattern14.x/8.9 key pattern
Licenseglobal.license.key, global.license.existingSecretglobal.license.secret.inlineSecret, global.license.secret.existingSecret
Elasticsearch authglobal.elasticsearch.auth.password, global.elasticsearch.auth.existingSecretglobal.elasticsearch.auth.secret.inlineSecret, global.elasticsearch.auth.secret.existingSecret
OpenSearch authglobal.opensearch.auth.password, global.opensearch.auth.existingSecretglobal.opensearch.auth.secret.inlineSecret, global.opensearch.auth.secret.existingSecret
Identity authglobal.identity.auth.{admin,identity,optimize,core}.existingSecretglobal.identity.auth.{admin,identity,optimize,core}.secret.existingSecret
Document Store (AWS)global.documentStore.type.aws.existingSecretglobal.documentStore.type.aws.accessKeyId.secret.existingSecret, global.documentStore.type.aws.secretAccessKey.secret.existingSecret
Document Store (GCP)global.documentStore.type.gcp.existingSecretglobal.documentStore.type.gcp.secret.existingSecret
Identity useridentity.firstUser.password, identity.firstUser.existingSecretidentity.firstUser.secret.inlineSecret, identity.firstUser.secret.existingSecret
Identity DBidentity.externalDatabase.password, identity.externalDatabase.existingSecretidentity.externalDatabase.secret.inlineSecret, identity.externalDatabase.secret.existingSecret
Web Modeler DBwebModeler.restapi.externalDatabase.password, webModeler.restapi.externalDatabase.existingSecretwebModeler.restapi.externalDatabase.secret.inlineSecret, webModeler.restapi.externalDatabase.secret.existingSecret
Web Modeler mailwebModeler.restapi.mail.smtpPasswordwebModeler.restapi.mail.secret.inlineSecret
Connectorsconnectors.security.authentication.oidc.existingSecretconnectors.security.authentication.oidc.secret.existingSecret
Orchestrationorchestration.security.authentication.oidc.existingSecretorchestration.security.authentication.oidc.secret.existingSecret

Additionally, global.secrets.* (including autoGenerated, name, annotations) has been removed entirely. All secrets must now be explicitly provided. See Secret management.

Other key changes​

13.x/8.8 values14.x/8.9 values
webModeler.restapi.externalDatabase.userRenamed to webModeler.restapi.externalDatabase.username.
<componentName>.extraConfiguration: {} (object)Changed to an array: <componentName>.extraConfiguration: []. Affects all components that support this key (connectors, orchestration, identity, console, optimize, webModeler). See Migrate extraConfiguration from 8.8 to 8.9.

Elasticsearch is now disabled by default​

The Elasticsearch subchart is no longer enabled by default. If you are using Elasticsearch, you must explicitly enable it in your values-8.9.yaml:

global:
  elasticsearch:
    enabled: true
elasticsearch:
  enabled: true

Secondary storage type is now required​

Camunda 8.9 no longer defaults to a secondary storage type. Explicitly setting orchestration.data.secondaryStorage.type in your values.yaml is recommended:

orchestration:
  data:
    secondaryStorage:
      type: elasticsearch # or "opensearch" or "rdbms"

The chart can auto-detect the type from global.elasticsearch.enabled or global.opensearch.enabled if you don't set it explicitly, but Helm will fail with a validation error if no secondary storage is configured at all.

Alternatively, if you do not need secondary storage, set global.noSecondaryStorage: true to run in engine-only mode. This disables all secondary-storage-dependent features and components and requires OIDC authentication.

Default REST port changed to 8080​

The Orchestration component's default HTTP port changed from 8090 to 8080. If you have hardcoded port 8090 in network policies, Ingress rules, health check probes, or service mesh configuration, update these references to 8080 or explicitly set orchestration.service.httpPort: 8090 in your values.yaml.

TLS secret pattern deprecated​

The legacy TLS secret configuration using *.tls.existingSecret is deprecated. Migrate to *.tls.secret.existingSecret. The legacy keys still work in 8.9 but will be removed in a future version.

Affected paths:

  • global.elasticsearch.tls.existingSecret → global.elasticsearch.tls.secret.existingSecret
  • global.opensearch.tls.existingSecret → global.opensearch.tls.secret.existingSecret
  • console.tls.existingSecret → console.tls.secret.existingSecret

Additionally, the JKS nesting level has been flattened:

  • global.elasticsearch.tls.jks.secret.existingSecret → global.elasticsearch.tls.secret.existingSecret
  • global.opensearch.tls.jks.secret.existingSecret → global.opensearch.tls.secret.existingSecret

Bitnami subcharts deprecated​

The Bitnami-based subcharts (identityPostgresql, identityKeycloak, webModelerPostgresql, elasticsearch) are deprecated in 8.9 and will be removed in 8.10. If any are enabled, Helm prints a deprecation warning. Plan migration to externally managed services before upgrading to 8.10.

global.elasticsearch and global.opensearch deprecated​

The global.elasticsearch.* and global.opensearch.* configuration trees are deprecated in 8.9 and will be removed in 8.10. Migrate to the new component-specific configuration:

8.8 key path8.9 replacement (Orchestration)8.9 replacement (Optimize)
global.elasticsearch.*orchestration.data.secondaryStorage.elasticsearch.*optimize.database.elasticsearch.*
global.opensearch.*orchestration.data.secondaryStorage.opensearch.*optimize.database.opensearch.*

The legacy keys still work in 8.9 with deprecation warnings. Existing deployments will continue to function without changes.

Identity profile renamed to admin​

The orchestration profile key orchestration.profiles.identity is deprecated and renamed to orchestration.profiles.admin. The chart automatically migrates the old key and prints a deprecation warning. Update your values-8.9.yaml to use orchestration.profiles.admin directly.

Example: upgrade values.yaml from 8.8 to 8.9​

This section shows a before-and-after example of a Helm values.yaml migrated from Camunda 8.8 to 8.9, covering the most common upgrade scenarios.

View example values files
# =========================
# Camunda 8.8 values.yaml
# =========================

global:
  # Secret auto-generation (removed in 8.9)
  secrets:
    autoGenerated: true

  # License using deprecated key
  license:
    existingSecret: camunda-license
    existingSecretKey: license-key

  # Elasticsearch auth using deprecated keys
  elasticsearch:
    # enabled: true was the default in 8.8
    auth:
      existingSecret: es-credentials
      existingSecretKey: password
    tls:
      existingSecret: es-tls-secret

  identity:
    auth:
      admin:
        existingSecret: admin-credentials
        existingSecretKey: password

identity:
  firstUser:
    existingSecret: identity-first-user
    existingSecretKey: password
  externalDatabase:
    existingSecret: identity-db-credentials
    existingSecretPasswordKey: password

webModeler:
  restapi:
    externalDatabase:
      user: modeler-user
      existingSecret: modeler-db-credentials
      existingSecretPasswordKey: password
    mail:
      smtpPassword: <SMTP_PASSWORD>

connectors:
  security:
    authentication:
      oidc:
        existingSecret: connectors-oidc
        existingSecretKey: client-secret
  extraConfiguration:
    customKey: customValue

orchestration:
  profiles:
    identity: true

Prepare and run the upgrade​

Add any upgrade-specific configuration required for the 8.9 upgrade.

Migrate extraConfiguration format​

In Camunda 8.9, the <componentName>.extraConfiguration Helm value changed from a map to an ordered list. If your values.yaml uses extraConfiguration for any component, you must convert it to the new format before upgrading.

See Migrate extraConfiguration from 8.8 to 8.9 for detailed instructions and examples.

Run the Helm upgrade​

After updating your values file with the required 8.9 configuration changes, run the Helm upgrade:

helm repo update
helm upgrade camunda camunda/camunda-platform \
  --namespace <NAMESPACE> \
  -f values-8.9.yaml

Monitor and validate the upgrade​

After triggering the Helm upgrade, monitor the rollout to ensure all pods return to a healthy state.

note

Unlike the 8.7 to 8.8 upgrade, the 8.8 to 8.9 upgrade does not run migration jobs. Only standard pod rollouts occur.

Watch pod rollout progress​

Watch the pods being upgraded via:

kubectl -n <NAMESPACE> get pods -w

You should see pods terminating and restarting with updated images.

Inspect logs (if required)​

If a pod fails to start, inspect its logs:

kubectl -n <NAMESPACE> logs <POD_NAME> --previous

Validate the upgrade​

  1. Confirm all pods are healthy:

    kubectl -n <namespace> get pods

  2. Confirm all pods are running 8.9.x images:

    kubectl -n <namespace> get pods -o jsonpath="{range .items[*]}{.metadata.name}{':\t'}{range .spec.containers[*]}{.image}{'\n'}{end}{end}"

  3. Verify access to Camunda components.

    For example:

    https://<your-domain>/<contextPath>/operate
    https://<your-domain>/<contextPath>/tasklist
    https://<your-domain>/<contextPath>/identity

  4. Verify authentication and authorization behavior, based on your configuration.

  5. Verify workers.

    Confirm your workers can still poll and complete jobs (for example, by running a known process end-to-end and checking worker logs/metrics).

Troubleshooting​

Upgrade failed due to missing secrets​

If your upgrade fails due to missing credentials (often when migrating from chart-managed secret generation to Kubernetes secrets), see Extract plaintext values and reference them as Kubernetes Secrets.

The Bitnami library chart used by Camunda can block upgrades when credentials were previously generated and persisted (for example, in PVCs). This is expected behavior to prevent secret regeneration.

For additional context, see Helm chart Bitnami legacy values file.

The following is an example of the error you might see:

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)

To complete the upgrade, migrate plaintext values to Kubernetes secrets and reference them from your values file as described in the secret management guide.

Upgrade failed with secondary storage validation error​

If Helm fails with a validation error about secondary storage type, the chart could not auto-detect which secondary storage to use. This happens when orchestration.data.secondaryStorage.type is not set and none of global.elasticsearch.enabled, global.opensearch.enabled, or orchestration.exporters.rdbms.enabled are true.

Add the required configuration to your values file:

orchestration:
  data:
    secondaryStorage:
      type: elasticsearch # or "opensearch" or "rdbms"

Alternatively, if you do not need secondary storage, set global.noSecondaryStorage: true to run in engine-only mode.