For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (unreleased)

Upgrade Camunda 8.9 to 8.10 using Helm

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

Upgrade procedure

All Camunda 8 upgrades must follow the required upgrade procedure: upgrade one minor version at a time and do not skip minors. For best stability and fix coverage, use the latest available patch in each minor before and after the minor upgrade.

See version compatibility checks.

Helm v4 CLI is required

Camunda 8.10 (chart 15.x) requires the Helm v4 CLI. Switch your tooling to the Helm v4 CLI before you run helm upgrade. Chart 14.x (8.9) already supports Helm v4, so you can switch while still on 8.9. No release-state migration is required when switching CLIs. See move from the Helm v3 CLI to v4.

Prerequisites​

Before upgrading, ensure you have met the following prerequisites:

PrerequisiteDescription
Confirm 8.9.x baselineConfirm your deployment is running an 8.9.x version before upgrading to 8.10. If you are upgrading from a version earlier than 8.9, upgrade one minor at a time. See upgrade Helm chart. For best stability, use the latest available 8.9.x patch.
Switch to the Helm v4 CLICamunda 8.10 (chart 15.x) requires the Helm v4 CLI. See Move from the Helm v3 CLI to v4.
Confirm upgrade eligibilityReview Prepare for upgrade to confirm upgrade eligibility and complete any required pre-upgrade actions for 8.10.
Confirm Helm chart supportReview the Camunda Helm chart version matrix and confirm the chart version deploying 8.10 is supported for your Kubernetes and Helm client versions.
BackupsCreate and verify backups for your Camunda data. See Backup and restore.
Check your values.yamlReview your existing values.yaml for the deprecated application configuration Helm keys that move to extraConfiguration in 8.10.
Test upgradeTest the upgrade in a non-production environment using a copy of your production configuration.

Create your 8.10 values file​

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

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

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

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

    To identify the latest available 15.x chart version, including prereleases, run:

    helm search repo camunda/camunda-platform --versions --devel \
      | awk '$2 ~ /^15\./ { print; exit }'

  3. Update values-8.10.yaml using the sections below.

  4. Compare values-8.10.yaml with values-8.10-default.yaml to identify any remaining new options, changed defaults, and deprecated settings before running helm upgrade.

Update your values file to 8.10​

Consolidate Console and Web Modeler into Camunda Hub​

Camunda 8.10 consolidates Console and Web Modeler into Camunda Hub. Console is no longer a standalone deployment; the camunda/hub image serves both feature sets.

Replace the legacy enablement keys with camundaHub.enabled and move overrides directly under camundaHub:

# Before (8.9)
console:
  enabled: true
webModeler:
  enabled: true
  restapi:
    resources:
      requests:
        memory: 1Gi

# After (8.10)
camundaHub:
  enabled: true
  restapi:
    resources:
      requests:
        memory: 1Gi

The legacy console.enabled and webModeler.enabled keys remain compatibility shims in 8.10 and emit deprecation warnings. Existing webModeler.* settings remain fallback values, but migrate them to the equivalent flattened camundaHub.* paths. Do not nest settings under camundaHub.webModeler or camundaHub.console.

If you mirror or pin images, update these repositories:

8.9 image8.10 image
camunda/web-modeler-restapi:8.9.xcamunda/hub:8.10.x
camunda/web-modeler-websockets:8.9.xcamunda/hub-websockets:8.10.x

The standalone console/console-sm image is no longer deployed. Configure the Hub repositories under camundaHub.restapi.image.repository and camundaHub.websockets.image.repository.

Because Console now runs in the Hub REST API pod, review camundaHub.restapi.resources after upgrading and adjust the requests and limits if the pod is throttled or runs out of memory.

Remove keys rejected by chart 15.x​

Chart 15.x rejects removed values before changing any workloads. Update or remove these values before upgrading:

Removed keyReplacement or action
global.ingress.hostUse global.host.
global.identity.keycloak.auth.existingSecretUse global.identity.keycloak.auth.secret.existingSecret.
global.identity.keycloak.auth.existingSecretKeyUse global.identity.keycloak.auth.secret.existingSecretKey.
global.elasticsearch.tls.existingSecretUse global.elasticsearch.tls.secret.existingSecret.
global.opensearch.tls.existingSecretUse global.opensearch.tls.secret.existingSecret.
orchestration.profiles.identityUse orchestration.profiles.admin.
webModeler.restapi.externalDatabase.userUse camundaHub.restapi.externalDatabase.username.
identityKeycloak, identityPostgresqlMigrate Keycloak and the Management Identity database to externally managed services. See Migrate from Bitnami charts.
webModelerPostgresqlMigrate the Camunda Hub database to external PostgreSQL and configure camundaHub.restapi.externalDatabase.
elasticsearchMigrate to external Elasticsearch or OpenSearch and configure the component-specific secondary storage values.

Deprecated application configuration Helm keys​

In chart 15.x (8.10), Helm keys that acted as thin proxies for a single application setting are being deprecated in favor of the component's extraConfiguration. These keys continue to work in 8.10: setting one to a non-default value logs a [camunda][warning] DEPRECATION message on helm install or helm upgrade. They are planned for removal in a later major chart version, so migrating them while on 8.10 keeps your values file ready for that removal.

Deprecations are still being added

Camunda 8.10 is under active development, and more keys may be deprecated across its release cycle. The tables below cover the keys deprecated at the time of writing; treat the [camunda][warning] DEPRECATION messages emitted by your own helm upgrade as the authoritative, up-to-date list for your chart version. Each message names the deprecated key and where to configure it instead.

extraConfiguration lets each component own its native application configuration file. Its format (an ordered list of file entries, mounted and imported via spring.config.import for Spring Boot components) is unchanged from 8.9. For how it works per component, exclusion of non-Spring files with springImport: false, and how to find the exact application property for a given setting, see Application configuration and extraConfiguration. The most reliable way to find a target property name is to generate the component's default configuration file and locate the equivalent property there.

For the deprecated keys below, the chart resolves the effective value from your extraConfiguration (and, for the document store, suppresses the generated environment variables) so your migrated configuration takes effect in 8.10. You do not need to remove the deprecated key at the same time; if both are set, the extraConfiguration value takes precedence.

Each deprecated key moves to the listed component's extraConfiguration, except where noted.

Orchestration​

Move these keys to orchestration.extraConfiguration:

Deprecated keyNotes
orchestration.logLevelRoot/log level in the app config or a log4j2.xml entry.
orchestration.log4j2Move to a file-content extraConfiguration entry (log4j2.xml) with springImport: false. See excluding files from spring.config.import.
orchestration.cpuThreadCount, orchestration.ioThreadCountcamunda.system.cpu-thread-count, camunda.system.io-thread-count.
orchestration.partitionCount, orchestration.replicationFactorcamunda.cluster.partition-count, camunda.cluster.replication-factor. Immutable after the first install; do not change on upgrade.
orchestration.data.snapshotPeriodcamunda.data.snapshot-period.
orchestration.data.disk.freeSpace.{processing,replication}camunda.data.primary-storage.disk.free-space.{processing,replication}.
orchestration.index.prefixSets two properties: camunda.data.secondary-storage.<elasticsearch|opensearch>.index-prefix and zeebe.broker.exporters.camundaexporter.args.connect.indexPrefix. If you set only one, the exporter and readers use different prefixes.
orchestration.index.replicascamunda.data.secondary-storage.<elasticsearch|opensearch>.number-of-replicas.
orchestration.history.retention.{enabled,minimumAge,policyName}camunda.data.secondary-storage.retention.{enabled,minimum-age} and ...<db>.history.policy-name.
orchestration.history.{delayBetweenRuns,maxDelayBetweenRuns,rolloverBatchSize,rolloverInterval,waitPeriodBeforeArchiving,elsRolloverDateFormat}zeebe.broker.exporters.camundaexporter.args.history.*.
orchestration.retention.{enabled,minimumAge,policyName}zeebe.broker.exporters.<elasticsearch|opensearch>.args.retention.* (Zeebe record index).
orchestration.security.authentication.unprotectedApicamunda.security.authentication.unprotectedApi. Cannot be true together with multi-tenancy checks. See Troubleshooting.
orchestration.security.authentication.oidc.{usernameClaim,clientIdClaim,groupsClaim,preferUsernameClaim,scope}camunda.security.authentication.oidc.{username-claim,client-id-claim,groups-claim,prefer-username-claim,scope}.
orchestration.security.authentication.oidc.backwardsCompatibleAudiencescamunda.security.authentication.oidc.audiences. This replaces the audience list. See Troubleshooting.
orchestration.security.authentication.authenticationRefreshIntervalcamunda.security.authentication.oidc.authenticationRefreshInterval.
orchestration.security.authorizations.enabledcamunda.security.authorizations.enabled.
orchestration.security.initialization.mappingRulescamunda.security.initialization.mapping-rules.
orchestration.security.initialization.authorizationscamunda.security.initialization.authorizations. The permission list field is permissions, not permissionTypes. See Troubleshooting.
orchestration.multitenancy.checks.enabled, orchestration.multitenancy.api.enabledcamunda.security.multiTenancy.checksEnabled, camunda.security.multiTenancy.apiEnabled.
orchestration.exporters.camunda.enabledcamunda.data.secondary-storage.autoconfigure-camunda-exporter.
orchestration.exporters.zeebe.replicaszeebe.broker.exporters.<elasticsearch|opensearch>.args.index.numberOfReplicas.
orchestration.security.authentication.oidc.redirectUrlBase redirect URL that sets three OIDC properties: camunda.security.authentication.oidc.redirect-uri (<base>/sso-callback), camunda.operate.identity.redirectRootUrl (<base>/operate), and camunda.tasklist.identity.redirectRootUrl (<base>/tasklist). If you set only one, the login callback, Operate, and Tasklist use different hosts.
orchestration.upgrade.allowPreReleaseImagescamunda.system.upgrade.enable-version-check (inverted: allowPreReleaseImages: true maps to enable-version-check: false).

Connectors​

Move these keys to connectors.extraConfiguration:

Deprecated keyNotes
connectors.logging.level."io.camunda.connector"logging.level."io.camunda.connector".

Optimize​

Move these keys to optimize.extraConfiguration, except where noted. Entries marked Native config use Optimize's own configuration property names rather than the camunda.* namespace; set them in optimize.extraConfiguration as well:

Deprecated keyNotes
optimize.logLevel, optimize.upgradeLogLevel, optimize.esLogLevellogging.level.{"io.camunda.optimize","io.camunda.optimize.upgrade","org.elasticsearch"}.
optimize.profilesspring.profiles.active.
optimize.caches.cloudTenantAuthorizations.{maxSize,minFetchIntervalSeconds}camunda.optimize.caches.cloud-tenant-authorizations.{max-size,min-fetch-interval-seconds}.
optimize.partitionCountNative config zeebe.partitionCount.
optimize.database.{elasticsearch,opensearch}.prefixNative config zeebe.name.
optimize.multitenancy.enabledMove to global.multitenancy.enabled (not extraConfiguration). This is a platform-wide switch that requires Identity with an external database. See multi-tenancy.

Camunda Hub​

Move these legacy keys to camundaHub.restapi.extraConfiguration:

Deprecated keyNotes
webModeler.restapi.mail.{fromAddress,fromName,smtpHost,smtpUser,smtpPort,smtpTlsEnabled}camunda.modeler.mail.* and spring.mail.*.
webModeler.restapi.logging.level.{"io.camunda.modeler","io.grpc"}logging.level.*.

Global​

Move each key to the consuming component's extraConfiguration:

Deprecated keyNotes
global.config.requestBodySizeThe relevant spring.servlet.multipart.*, server.tomcat.max-http-form-post-size, and message-size properties per component.
global.zeebeClusterNamezeebe.broker.cluster.clusterName on the orchestration component.
global.documentStore.type.{aws,gcp,inmemory}.storeIdThe unified camunda.document.* config (default-store-id plus the store definition) on each document-consuming component. See Troubleshooting.

Migrate extraConfiguration entries​

The extraConfiguration value format is unchanged from 8.9. If you already use extraConfiguration, no format change is required for this upgrade. For the mechanics, per-component behavior, and a worked example of moving settings into a configuration file, see Application configuration and extraConfiguration.

The following condensed example shows the shape of the migration for the orchestration component:

# Before (8.9, deprecated keys)
orchestration:
  logLevel: debug
  partitionCount: "3"
  data:
    snapshotPeriod: 10m
  history:
    retention:
      enabled: true
      minimumAge: 45d

# After (8.10, extraConfiguration)
orchestration:
  extraConfiguration:
    - file: application-migrated.yaml
      content: |
        zeebe:
          log:
            level: debug
        camunda:
          cluster:
            partition-count: 3
          data:
            snapshot-period: 10m
            secondary-storage:
              retention:
                enabled: true
                minimum-age: 45d

Run the Helm upgrade​

After updating your values file with the required 8.10 configuration changes, run the Helm upgrade with the Helm v4 CLI:

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

Monitor and validate the upgrade​

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

Watch pod rollout progress​

kubectl -n <NAMESPACE> get pods -w

You should see pods terminating and restarting with updated images.

Inspect logs (if required)​

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

Validate the upgrade​

  1. Confirm all pods are healthy and running 8.10.x images:

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

  2. Review the helm upgrade output for any [camunda][warning] DEPRECATION messages. Each one names a key still to migrate before it is removed in a later major chart version.

  3. Verify access to Camunda components, authentication and authorization behavior, and that your workers can still poll and complete jobs.

Troubleshooting​

Upgrade failed due to missing secrets​

If your upgrade fails due to missing credentials, see Extract plaintext values and reference them as Kubernetes Secrets. For additional context, see Helm chart Bitnami legacy values file.

Upgrade failed with secondary storage validation error​

If Helm fails with a validation error about secondary storage type, set it explicitly:

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

Alternatively, if you do not need secondary storage, set global.noSecondaryStorage: true.

Backwards-compatible audiences replace the audience list​

The deprecated orchestration.security.authentication.oidc.backwardsCompatibleAudiences appended its values to the default audiences, but its target, camunda.security.authentication.oidc.audiences, replaces the whole list. If you migrate it verbatim, the broker only accepts your extra audience and rejects the component tokens (operate-api, tasklist-api, zeebe-api, and so on) with UNAUTHENTICATED: Expected a valid token. List the full default audience set alongside your backwards-compatible audience in audiences.

Initialization authorizations report "No permissionTypes provided"​

If the orchestration pod fails to start with IdentityInitializationException: Cannot initialize configured authorizations: No permissionTypes provided, the authorization entry uses the wrong field name. Under camunda.security.initialization.authorizations, the permission list field is permissions, not permissionTypes.

Custom document store ID​

A non-default global.documentStore.type.inmemory.storeId (or aws/gcp) cannot be used through the deprecated key alone: the default store ID is derived from global.documentStore.activeStoreId (the store type), never the custom store ID, so the app fails with Default document store ID does not match any configured document store. Migrate the whole document configuration to camunda.document.* (default-store-id plus the store definition) in each document-consuming component's extraConfiguration.

Multi-tenancy with an unprotected API​

camunda.security.multiTenancy.checksEnabled: true cannot be combined with camunda.security.authentication.unprotectedApi: true; the orchestration pod fails with Multi-tenancy is enabled ... but the API is unprotected. Protect the API when multi-tenancy is enabled.