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

Upgrade Camunda components from 8.9 to 8.10

note

This page is a work in progress for Camunda 8.10 and will be updated as upgrade requirements are finalized.

Review component-level actions that may be required when upgrading a Camunda 8 Self-Managed deployment from 8.9.x to 8.10.x.

About​

Use this page with the deployment upgrade guide for your environment. Start with the Upgrade Camunda 8 overview, then apply any component-specific steps that match your setup.

Camunda Hub​

In 8.10, Camunda Hub replaces Console and Web Modeler. To support this change:

  • Console-specific configurations have been removed.
  • Cluster configurations have been updated.

If you use a custom configuration, review this section and make applicable changes. Otherwise, this section is not applicable to your setup.

Console configuration​

Console no longer exists in 8.10. Therefore, if you've configured Console with custom settings, remove those settings:

  • If using application properties, remove the top-level camunda.console object. The application will fail on startup if this is configured.
  • If using environment variables, remove the following variables:
    • CAMUNDA_CONSOLE_CONTEXT_PATH
    • CAMUNDA_CONSOLE_CUSTOMERID
    • CAMUNDA_CONSOLE_DISABLE_AUTH
    • CAMUNDA_CONSOLE_EXPERIMENTAL_DISCOVERY_MODE
    • CAMUNDA_CONSOLE_INSTALLATIONID
    • CAMUNDA_CONSOLE_REDIRECT_TRAILING_SLASH
    • CAMUNDA_CONSOLE_REDIRECT_URL
    • CAMUNDA_CONSOLE_TELEMETRY

Management Identity roles and permissions​

Management Identity only adds roles, applications, and permissions on startup; it never removes them. As a result:

  • If you hold the Console role, you automatically gain management access to Hub's cluster pages through a new admin:clusters permission after upgrading. No manual role reassignment is required. DevOps is the forward-looking name for the same access.
  • If you hold the Web Modeler Admin role, you also automatically gain full access to Hub's cluster pages after upgrading — a broader grant than the Console role's management-only access, since admin:* also carries modeler-admin capabilities. In 8.9, this role's admin:* permission only covered Web Modeler super-user mode and publishing connector templates; in 8.10, the same permission additionally reaches Hub's cluster pages. No manual role reassignment is required. Hub Admin is the forward-looking name for the same access.
  • After upgrading, your Keycloak also gains roles named Hub and Hub Admin, provisioned alongside your existing Web Modeler and Web Modeler Admin roles (which are kept for backward compatibility and keep working unchanged). This applies to every installation, not just new ones, so you may see both name pairs after upgrading. Both name pairs grant identical permissions; assign whichever name makes sense for your users.
  • The standalone Keycloak Console application and console-api audience are no longer provisioned by Management Identity — Console's cluster-management pages are now part of the Hub UI application, so a separate OIDC application/client for Console is no longer needed. Your existing console client and its role mappings are not deleted automatically. If you no longer need them, remove them manually from Keycloak (or your OIDC provider).

If you rely on least-privilege access to cluster management, review who holds the Console and Web Modeler Admin / Hub Admin roles before upgrading. See the 8.10 release announcements for a summary of this and other Hub role changes in 8.10.

For the full list of default roles, applications, and permissions in 8.10, see manage roles and manage access and permissions.

Cluster configuration​

The following settings have been ported from the Console configuration in 8.9 to Camunda Hub in 8.10:

8.98.10
camunda.console.managed.releases[0].tagscamunda.modeler.clusters[0].tags
camunda.console.managed.releases[0].custom-propertiescamunda.modeler.clusters[0].custom-properties
camunda.console.managed.releases[0].componentscamunda.modeler.clusters[0].components
camunda.console.managed.releases[0].components[0].idcamunda.modeler.clusters[0].components[0].type
camunda.console.managed.releases[0].components[0].urlcamunda.modeler.clusters[0].components[0].urls.<webapp|rest|grpc>
camunda.console.managed.releases[0].components[0].readinesscamunda.modeler.clusters[0].components[0].urls.readiness
camunda.console.managed.releases[0].components[0].metricsRemoved.

Cluster configuration example​

Console 8.9 configuration:

camunda:
  console:
    managed:
      releases:
        - name: camunda-platform
          namespace: qa-camunda-platform
          version: 8.9.0
          tags:
            - dev
          custom-properties:
            - description: "Monitoring"
              links:
                - name: "Grafana"
                  url: "http://localhost:3000"
                - name: "Prometheus"
                  url: "http://localhost:9090"
            - description: "Documentation"
              links:
                - name: "Wiki"
                  url: "http://localhost:8090/wiki"
          components:
            - name: camunda-platform
              namespace: camunda-platform-namespace
              version: 9.1.2
              components:
                - name: Console
                  id: console
                  version: 8.9-SNAPSHOT
                  url: https://qa.ci.distro.ultrawombat.com/
                  readiness: http://camunda-platform-console.qa-camunda-platform:9100/health/readiness
                  metrics: http://camunda-platform-console.qa-camunda-platform:9100/prometheus
                - name: Keycloak
                  id: keycloak
                  url: https://qa.ci.distro.ultrawombat.com/auth/
                - name: Identity
                  id: identity
                  version: SNAPSHOT
                  url: https://qa.ci.distro.ultrawombat.com/identity
                  readiness: http://camunda-platform-identity.qa-camunda-platform:82/actuator/health
                  metrics: http://camunda-platform-identity.qa-camunda-platform:82/actuator/prometheus
                - name: WebModeler
                  id: webModelerWebApp
                  version: SNAPSHOT
                  url: https://qa.ci.distro.ultrawombat.com/modeler
                  readiness: http://camunda-platform-web-modeler-restapi.qa-camunda-platform:8091/modeler/health/readiness
                  metrics: http://camunda-platform-web-modeler-restapi.qa-camunda-platform:8091/modeler/metrics
                - name: Optimize
                  id: optimize
                  version: 8.9-SNAPSHOT
                  url: https://qa.ci.distro.ultrawombat.com/optimize
                  readiness: http://camunda-platform-optimize.qa-camunda-platform:80/optimize/api/readyz
                  metrics: http://camunda-platform-optimize.qa-camunda-platform:8092/actuator/prometheus
                - name: Connectors
                  id: connectors
                  version: 8.9-SNAPSHOT
                  url: http://camunda-platform-connectors.qa-camunda-platform:8080/connectors
                  readiness: http://camunda-platform-connectors.qa-camunda-platform:8080/connectors/actuator/health/readiness
                  metrics: http://camunda-platform-connectors.qa-camunda-platform:8080/connectors/actuator/prometheus
                - name: Operate
                  id: operate
                  version: 8.9-SNAPSHOT
                  url: https://qa.ci.distro.ultrawombat.com/core/operate
                  readiness: http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/health/readiness
                  metrics: http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/prometheus
                - name: Tasklist
                  id: tasklist
                  version: 8.9-SNAPSHOT
                  url: https://qa.ci.distro.ultrawombat.com/core/tasklist
                  readiness: http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/health/readiness
                  metrics: http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/prometheus
                - name: Orchestration Admin
                  id: orchestrationIdentity
                  version: 8.9-SNAPSHOT
                  url: https://qa.ci.distro.ultrawombat.com/core/admin
                  readiness: http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/health/readiness
                  metrics: http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/prometheus
                - name: Orchestration Cluster
                  id: orchestration
                  version: 8.9-SNAPSHOT
                  urls:
                    grpc: https://grpc-qa.ci.distro.ultrawombat.com
                    http: https://qa.ci.distro.ultrawombat.com/core
                    readiness: http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/health/readiness
                    metrics: http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/prometheus

Camunda Hub 8.10 configuration:

camunda:
  modeler:
    clusters:
      - id: "camunda-platform"
        name: "camunda-platform"
        namespace: "qa-camunda-platform"
        version: "8.10.0"
        authentication: BEARER_TOKEN
        authorizations:
          enabled: true
        tags:
          - "dev"
        custom-properties:
          - description: "Monitoring"
            links:
              - name: "Grafana"
                url: "http://localhost:3000"
              - name: "Prometheus"
                url: "http://localhost:9090"
          - description: "Documentation"
            links:
              - name: "Wiki"
                url: "http://localhost:8090/wiki"
        components:
          - name: "Identity"
            type: "identity"
            version: "8.10-SNAPSHOT"
            urls:
              webapp: "https://qa.ci.distro.ultrawombat.com/identity"
              readiness: "http://camunda-platform-identity.qa-camunda-platform:82/actuator/health"
          - name: "Camunda Hub"
            type: "hub"
            version: "8.10-SNAPSHOT"
            urls:
              webapp: "https://qa.ci.distro.ultrawombat.com/modeler"
              readiness: "http://camunda-platform-web-modeler-restapi.qa-camunda-platform:8091/modeler/health/readiness"
          - name: "Optimize"
            type: "optimize"
            version: "8.10-SNAPSHOT"
            urls:
              webapp: "https://qa.ci.distro.ultrawombat.com/optimize"
              readiness: "http://camunda-platform-optimize.qa-camunda-platform:80/optimize/api/readyz"
          - name: "Connectors"
            type: "connectors"
            version: "8.10.0"
            urls:
              rest: "http://camunda-platform-connectors.qa-camunda-platform:8080/connectors"
              readiness: "http://camunda-platform-connectors.qa-camunda-platform:8080/connectors/actuator/health/readiness"
          - name: "Operate"
            type: "operate"
            version: "8.10-SNAPSHOT"
            urls:
              webapp: "https://qa.ci.distro.ultrawombat.com/core/operate"
              readiness: "http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/health/readiness"
          - name: "Tasklist"
            type: "tasklist"
            version: "8.10-SNAPSHOT"
            urls:
              webapp: "https://qa.ci.distro.ultrawombat.com/core/tasklist"
              readiness: "http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/health/readiness"
          - name: "Orchestration Admin"
            type: "admin"
            version: "8.10-SNAPSHOT"
            urls:
              webapp: "https://qa.ci.distro.ultrawombat.com/core/admin"
              readiness: "http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/health/readiness"
          - name: "Orchestration Cluster"
            type: "orchestration"
            version: "8.10-SNAPSHOT"
            urls:
              grpc: "https://grpc-qa.ci.distro.ultrawombat.com"
              rest: "https://qa.ci.distro.ultrawombat.com/core"
              readiness: "http://camunda-platform-zeebe.qa-camunda-platform:9600/core/actuator/health/readiness"

Authentication configuration​

In 8.10, Camunda Hub accepts the same camunda.security.authentication.oidc.* configuration as the Orchestration Cluster.

No action is required to upgrade to 8.10. Hub translates its 8.9 authentication settings to the new equivalents at startup, and your existing configuration continues to work. Those 8.9 settings are deprecated, however, and are removed in 8.11, so use the following mapping to migrate before upgrading to 8.11:

8.98.10
spring.security.oauth2.resourceserver.jwt.issuer-uricamunda.security.authentication.oidc.issuer-uri
camunda.modeler.oauth2.client-idcamunda.security.authentication.oidc.client-id
camunda.modeler.oauth2.token.username-claimcamunda.security.authentication.oidc.username-claim
spring.security.oauth2.resourceserver.jwt.audiences
camunda.modeler.security.jwt.audience.internal-api
camunda.modeler.security.jwt.audience.public-api		camunda.security.authentication.oidc.audiences

Note the following:

  • The three 8.9 audience settings are merged into the single comma-separated camunda.security.authentication.oidc.audiences list.
  • If you set both an 8.9 setting and its 8.10 equivalent, the 8.10 setting takes precedence.
  • The 8.9 settings are removed in 8.11. Migrate to their 8.10 equivalents before upgrading to 8.11.
  • Cross-origin resource sharing (CORS) settings are unchanged. Hub continues to use its own CORS configuration.
  • User, group, role, tenant, and permission management is unchanged in 8.10, and is still handled by Management Identity.
  • If you set more than one of the three 8.9 audience properties, set camunda.security.authentication.oidc.audiences explicitly so the resulting list is the one you intend.

For the full Hub authentication configuration, see Camunda Hub authentication.

Component types​

console and keycloak are no longer valid component types. The application will fail on startup if you've configured a console or keycloak component.

Additionally, the following component types have been renamed:

  • webModelerWebApp → hub
  • orchestrationIdentity → admin

The old values are still accepted for backward compatibility, but you should update your configuration to use the new values.

camunda:
  modeler:
    clusters:
      - id: camunda-platform
        # other fields...
        components:
          - name: "Console"
            type: "console" # type cannot be "console" or "keycloak"
            version: "8.10-SNAPSHOT"
            urls:
              webapp: "https://qa.ci.distro.ultrawombat.com/"
              readiness: "http://camunda-platform-console.qa-camunda-platform:9100/health/readiness"

Dynamic cluster management​

In Camunda 8.8 and 8.9, you could use CAMUNDA_CONSOLE_EXPERIMENTAL_DISCOVERY_MODE to expose the discovery API, which allowed clusters to send license information and register themselves with Console. This experimental feature is now replaced by a new feature flag in the Camunda Hub configuration: DYNAMIC_CLUSTER_MANAGEMENT_ENABLED.

With dynamic cluster management, clusters can regularly send license information to a discovery endpoint:

POST /api/v2/clusters

With that information, Camunda Hub registers the cluster with minimal data and no management functionality in the user interface. This behavior is similar to CAMUNDA_CONSOLE_EXPERIMENTAL_DISCOVERY_MODE.

However, unlike in Console, where cluster records were cleaned up on restart, Camunda Hub cluster registrations persist through restarts. So you'll need to remove them yourself using the remove cluster registration endpoint:

DELETE /api/v2/clusters/{clusterId}

Read more about dynamic cluster management in the Camunda Hub properties reference.

Elasticsearch/OpenSearch Exporter​

Default replica count changed​

In 8.10, the default value of number-of-replicas for Elasticsearch/OpenSearch Exporter indices changed from 0 to 1.

This applies to new indices created after upgrading. Existing indices are not affected.

  • Single-node clusters: Set number-of-replicas: 0 explicitly in your exporter configuration to avoid yellow cluster health. On a single node, replicas cannot be assigned and remain unassigned, which causes the cluster to report yellow health and may trigger monitoring alerts.
  • Multi-node clusters: No action required. The new default improves fault tolerance. Note that each replica stores a full copy of the shard data, so enabling replicas increases disk usage for new indices.

Optimize​

Default objectVariable inclusion changed​

This is a breaking change for Self-Managed. In 8.10, the default value of zeebe.includeObjectVariableValue changed from true to false. Optimize no longer flattens object variables into per-property fields or stores their raw value by default. See the 8.10 breaking change announcement for the full rationale.

Setting8.98.10
zeebe.includeObjectVariableValuetruefalse

Action: If your reports, filters, or Raw Data Reports rely on flattened object variable properties, set zeebe.includeObjectVariableValue: true (environment variable CAMUNDA_OPTIMIZE_ZEEBE_INCLUDE_OBJECT_VARIABLE=true) before upgrading:

zeebe:
  includeObjectVariableValue: true

Optimize logs a WARN on startup whenever object variable values are not being imported. The message includes the opt-in setting.

Object variables configuration

In 8.10, Optimize accepts the same camunda.security.* configuration as the Orchestration Cluster, and its authentication behavior changes accordingly. For the full picture, including the new session model and API-consumer behavior changes, see Optimize authentication in Self-Managed. The following two sections cover the configuration key changes only.

Legacy security configuration keys are deprecated​

The following legacy keys are deprecated in favor of camunda.security.*. They remain supported through 8.10 and are removed in 8.11, along with the legacy security stack.

Optimize maps each recognized legacy key to its replacement automatically and logs a deprecation warning naming the replacement, so existing deployments keep working unchanged through 8.10.

Legacy keyReplacement
CAMUNDA_OPTIMIZE_IDENTITY_ISSUER_URLcamunda.security.authentication.oidc.issuer-uri
CAMUNDA_OPTIMIZE_IDENTITY_CLIENTIDcamunda.security.authentication.oidc.client-id
CAMUNDA_OPTIMIZE_IDENTITY_CLIENTSECRETcamunda.security.authentication.oidc.client-secret
CAMUNDA_OPTIMIZE_IDENTITY_AUDIENCEcamunda.security.authentication.oidc.audiences
CAMUNDA_OPTIMIZE_AUTH0_CLIENTIDcamunda.security.authentication.oidc.client-id
CAMUNDA_OPTIMIZE_AUTH0_CLIENTSECRETcamunda.security.authentication.oidc.client-secret
CAMUNDA_OPTIMIZE_AUTH0_DOMAINcamunda.security.authentication.oidc.issuer-uri (issuer is derived from the Auth0 domain)
CAMUNDA_OPTIMIZE_AUTH0_ORGANIZATIONcamunda.security.saas.*
CAMUNDA_OPTIMIZE_CLIENT_AUDIENCEcamunda.security.authentication.oidc.audiences
CAMUNDA_OPTIMIZE_CLIENT_CLUSTERIDcamunda.security.saas.* (also derives the redirect URI ?uuid and the servlet context path)
CAMUNDA_OPTIMIZE_M2M_ACCOUNTS_AUTH0_AUDIENCEcamunda.security.authentication.oidc.audiences
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URIcamunda.security.authentication.oidc.jwk-set-uri
CAMUNDA_OPTIMIZE_API_AUDIENCEcamunda.security.authentication.oidc.audiences
CAMUNDA_OPTIMIZE_SECURITY_RESPONSE_HEADERS_HSTS_MAX_AGEcamunda.security.http-headers.hsts.max-age-in-seconds (a negative value disables the header)
camunda.identity.issuerBackendUrlcamunda.security.authentication.oidc.issuer-uri, or one of the endpoint-specific overrides (jwk-set-uri, authorization-uri, token-uri, user-info-uri) if your Keycloak back channel is reachable at a different address than the public-facing issuer
camunda.identity.clientIdcamunda.security.authentication.oidc.client-id
camunda.identity.clientSecretcamunda.security.authentication.oidc.client-secret

Note the following:

  • Precedence: If you set both a legacy key and its camunda.security.* replacement, the camunda.security.* value wins.
  • audiences replaces, not merges: If you set camunda.security.authentication.oidc.audiences yourself, that list replaces the audiences from CAMUNDA_OPTIMIZE_IDENTITY_AUDIENCE and CAMUNDA_OPTIMIZE_API_AUDIENCE. Include every audience you still need in your explicit list.
  • CAMUNDA_OPTIMIZE_IDENTITY_BASE_URL is not deprecated: Keep it set. Optimize still uses it to look up users, for example when adding users to a collection.

Action: Migrate to the camunda.security.* keys before upgrading to 8.11, when the legacy keys and the legacy security stack are both removed.

Keys with no replacement​

The following keys are no longer used in 8.10. Optimize still starts if you leave them in place, but they have no effect, so remove them:

  • CAMUNDA_OPTIMIZE_SECURITY_AUTH_TOKEN_SECRET
  • CAMUNDA_OPTIMIZE_SECURITY_AUTH_COOKIE_MAX_SIZE
  • CAMUNDA_OPTIMIZE_SECURITY_AUTH_COOKIE_SAME_SITE_ENABLED
  • OPTIMIZE_API_ACCESS_TOKEN
  • security.responseHeaders.X-XSS-Protection

If you use OPTIMIZE_API_ACCESS_TOKEN to call the Optimize API, switch those callers to OIDC bearer tokens.

Zeebe​

Job leasing during the rolling upgrade​

Camunda 8.10 introduces job leasing. During a rolling upgrade from 8.9, jobs on partitions that are still running 8.9 return a null leaseToken, even when activated with withLease set to true, because 8.9 brokers do not support job leasing.

If your worker requires the lease to process a job safely, treat a null leaseToken as not yet supported on that partition: fail the job with a retry backoff, and set retries back to the job's current value so the fail doesn't burn through them while the upgrade is in progress. The lease becomes available after that job's partition leader is upgraded to 8.10, and the retry converges.

When using the REST API, a gateway instance still running 8.9 rejects the unknown withLease field with a 400 error instead of returning null. This handling is no longer required after every gateway in the cluster has been upgraded to 8.10.

final JobHandler paymentJobHandler =
    (jobClient, job) -> {
        final String leaseToken = job.getLeaseToken();

        if (leaseToken == null) {
            // This partition hasn't upgraded to 8.10 yet. Fail with retries
            // preserved so the job converges once the upgrade completes,
            // instead of being burned into an incident.
            jobClient
                .newFailCommand(job)
                .retries(job.getRetries())
                .retryBackoff(Duration.ofSeconds(30))
                .errorMessage("Lease required but not returned; retrying until the partition upgrades to 8.10")
                .send();
            return;
        }

        // process the job

        jobClient.newCompleteCommand(job).send();
    };

client
    .newWorker()
    .jobType("process-payment")
    .handler(paymentJobHandler)
    .withLease(true)
    .open();