Skip to main content
Version: 8.8

Upgrade Camunda components from 8.7 to 8.8

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

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.

Single Elasticsearch/OpenSearch instance​

Using more than one isolated Elasticsearch/OpenSearch instance for exported Zeebe, Operate, and Tasklist data is no longer supported.

If your environment uses multiple Elasticsearch/OpenSearch instances, you must manually migrate all data into a single Elasticsearch/OpenSearch cluster before upgrading to Camunda 8.8.

The migration must include:

  • Zeebe indices
  • Operate indices
  • Tasklist indices
  • Index templates
  • Aliases
  • ILM or ISM policies
important

This step must be completed before all other migration steps.

Update any custom prefixes​

Camunda 8.8 introduces a harmonized index schema that uses a single common index prefix.

If your installation uses custom index prefixes, you must migrate all existing indices to a common prefix before upgrading. This ensures the Camunda Exporter, REST API, and other consumers are configured correctly.

Prefix migration​

warning

Prefix migration modifies the secondary storage in preparation for the Camunda 8.8 upgrade. These changes are irreversible.

Before you proceed:

  • Create a full backup of your Elasticsearch/OpenSearch cluster.
  • Schedule downtime.
  • Ensure no access to Camunda indices during migration.

Do not restart the cluster on Camunda 8.7 after this migration.

Complete the following steps:

  1. Shut down your Camunda 8.7 cluster (for example, scale all components to zero replicas).
  2. From the camunda/bin directory, run the prefix-migration script.
    • Make sure your configuration in camunda/config reflects the existing custom prefixes.
    • Expose the configuration to the script (for example, using SPRING_CONFIG_ADDITIONALLOCATION=/path/to/application.yaml ./camunda/bin/prefix-migration).
    • Alternatively, set the configuration using environment variables.

Prefix migration example​

Environment variables:

export CAMUNDA_OPERATE_ELASTICSEARCH_INDEX_PREFIX=old-operate-prefix ;\
export CAMUNDA_TASKLIST_ELASTICSEARCH_INDEX_PREFIX=old-tasklist-prefix ;\
export CAMUNDA_DATA_SECONDARYSTORAGE_ELASTICSEARCH_INDEXPREFIX=some-new-prefix ;\
export CAMUNDA_DATA_SECONDARYSTORAGE_ELASTICSEARCH_URL=http://localhost:9200 ;\
export CAMUNDA_DATA_SECONDARYSTORAGE_TYPE=elasticsearch ;\
./bin/prefix-migration

application.yaml:

camunda:
  tasklist:
    elasticsearch-index-prefix: old-tasklist-prefix
  operate:
    elasticsearch-index-prefix: old-operate-prefix
  data:
    secondary-storage:
      type: elasticsearch
      elasticsearch:
        url: http://localhost:9200
        index-prefix: some-new-prefix

If only Tasklist or Operate uses a custom prefix, set the prefix only for the affected component.

After prefix migration completes, update your configuration before upgrading to Camunda 8.8.

For example, if the new prefix is some-new-prefix:

CAMUNDA_DATA_SECONDARYSTORAGE_ELASTICSEARCH_INDEXPREFIX=some-new-prefix
ZEEBE_BROKER_EXPORTERS_CAMUNDA_ARGS_CONNECT_INDEXPREFIX=some-new-prefix

Once complete, the secondary storage is ready for the Camunda 8.8 upgrade.

Camunda Orchestration Cluster Identity data migration​

Camunda 8.8 introduces Orchestration Cluster Identity as a dedicated identity component. Existing identity data stored in Management Identity must be migrated to ensure continued access to users, roles, groups, tenants, and authorizations.

For an overview of the architectural change, see Identity and management changes in 8.8.

To support this transition, Camunda provides an Identity Migration Application that migrates identity data from Management Identity to Orchestration Cluster Identity.

RBA migration impact

If you use Resource-Based Authorization (RBA) and have users assigned to roles with zeebe-api:write permissions (including the default Zeebe role), users may receive wildcard permissions after migration.

While a user remains a member of such a role, access in Tasklist and Operate will not be restricted to specific resources.

Run the Identity Migration Application​

You can run the migration application:

The migration is idempotent and can be safely re-run.

Run the migration natively​

./bin/identity-migration

Run the migration using Docker​

Override the default entrypoint of the official Camunda image:

docker run --entrypoint /usr/local/camunda/bin/identity-migration camunda/camunda:8.8.0

Helm chart deployments​

In Helm-based deployments, the Identity Migration Application runs as a Kubernetes Job, independent of other migration processes.

Key characteristics:

  • Idempotent execution
  • Runs separately from data migration
  • Produces detailed logs
  • Migration resources can be removed after successful completion

The migration requires a dedicated Keycloak client with read-only access to your Identity Resource Server. When you enable Identity migration, the Helm chart automatically configures the required migration client. You can remove this client after migration is complete.

Monitor migration completion​

Verify successful completion by checking for the following log entries:

INFO io.camunda.migration.identity.handler.sm.AuthorizationMigrationHandler - Authorization migration complete: Created {num} out of {num} authorizations. Skipped {num} as they already exist.
INFO io.camunda.migration.identity.handler.sm.ClientMigrationHandler - Client authorization migration complete: Created {num} out of {num} authorizations. Skipped {num} as they already exist.
INFO io.camunda.migration.identity.handler.sm.MappingRuleMigrationHandler - Mapping rule migration completed: Created {num} out of {num} mapping rules, the remaining existed already. Assigned {num} roles out of {num} attempted, the remaining were already assigned. Assigned  tenants out of {num} attempted, the remaining were already assigned.
INFO io.camunda.migration.identity.handler.sm.RoleMigrationHandler - Role Migration completed: Created {num} roles out of {num} total roles.
INFO io.camunda.migration.identity.handler.sm.TenantMigrationHandler - Tenant migration completed: Created {num} out of {num} tenants, the remaining existed already.
INFO io.camunda.migration.identity.handler.sm.UserRoleMigrationHandler - Tenant migration completed: User Role membership migration completed: Assigned {num} roles out of {num} roles.

Configure the Identity Migration Application​

The migration application supports two source setups:

  • Management Identity with Keycloak (default in 8.7)
  • Management Identity with OIDC

Configuration can be provided using:

  • application.yaml
  • Environment variables

The default configuration file locations are:

  • ./config/application.yaml (native)
  • /usr/local/camunda/config/application.yaml (Docker)

Common configuration for the Identity Migration Application​

The migration application must:

  • Join the Orchestration Cluster to create Identity Access Management records
  • Access the Management Identity API with read permissions
Environment variableDescriptionRequired value
CAMUNDA_MIGRATION_IDENTITY_MODEMode of the migration app.In case of the Camunda Identity 8.7 default (Keycloak) setup: KEYCLOAK.
In case of the Camunda Identity 8.7 with OIDC setup: OIDC
CAMUNDA_MIGRATION_IDENTITY_RESOURCEAUTHORIZATIONSENABLEDSignals whether Resource Authorizations were used in the 8.7, defaults to false.Must be true in case Resource Authorizations were used.
CAMUNDA_MIGRATION_IDENTITY_CLUSTER_CLUSTERNAMEName of the Orchestration cluster.Same value as used on the cluster for ZEEBE_BROKER_CLUSTER_CLUSTERNAME
CAMUNDA_MIGRATION_IDENTITY_CLUSTER_CLUSTERSIZESize of the Orchestration cluster.Same value as used on the cluster for ZEEBE_BROKER_CLUSTER_CLUSTERSIZE
CAMUNDA_MIGRATION_IDENTITY_CLUSTER_PARTITIONSCOUNTPartition count of the Orchestration cluster.Same value as used on the cluster for ZEEBE_BROKER_CLUSTER_PARTITIONSCOUNT
CAMUNDA_MIGRATION_IDENTITY_CLUSTER_REPLICATIONFACTORReplication factor of the Orchestration cluster.Same value as used on the cluster for ZEEBE_BROKER_CLUSTER_REPLICATIONFACTOR
CAMUNDA_MIGRATION_IDENTITY_CLUSTER_INITIALCONTACTPOINTSList of known cluster hosts within the Orchestration cluster.Same value as used on the cluster for ZEEBE_BROKER_CLUSTER_INITIALCONTACTPOINTS
CAMUNDA_MIGRATION_IDENTITY_MANAGEMENTIDENTITY_AUDIENCEThe audience for accessing the Management Identity APIIn case of a default Keycloak setup, it is camunda-identity-resource-server, in case of OIDC, it is user defined.
CAMUNDA_MIGRATION_IDENTITY_MANAGEMENTIDENTITY_BASEURLThe URL under which Management Identity can be accessed by the Identity Migration ApplicationMust be a valid absolute URL to the Management Identity server, e.g. http://management-identity:8080.
CAMUNDA_MIGRATION_IDENTITY_MANAGEMENTIDENTITY_CLIENTIDThe client id for accessing Management Identity.The clientId set requires to have the read permission granted for the Camunda Identity Resource Server API in Management Identity
CAMUNDA_MIGRATION_IDENTITY_MANAGEMENTIDENTITY_CLIENTSECRETThe client secret for accessing Management Identity.Matching secret for configured clientId.
CAMUNDA_MIGRATION_IDENTITY_MANAGEMENTIDENTITY_ISSUERBACKENDURLThe URL under which the Token Issuer can be accessed.Use the same as used by Management Identity for CAMUNDA_IDENTITY_ISSUER_BACKEND_URL.

Entity ID conversion rules​

During migration, entity IDs are transformed to meet Orchestration Cluster validation rules:

  • Converted to lowercase
  • Characters outside [a-z0-9_@.-] replaced with _

You can customize this behavior using the provided configuration options.

Environment variableDescriptionDefault value
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_DEFAULT_LOWERCASEIf true, the IDs of ROLES, GROUPS, MAPPING RULES and USERS will be lowercased. Specific entities configuration have precedence.true
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_DEFAULT_PATTERNConfigure the regex character class that identifies characters to be replaced with an underscore (_) during entities migration. Specific entities configuration have precedence. This pattern must not be more permissive then the Orchestration Cluster's ID validation pattern[^a-z0-9_@.-]
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_ROLE_LOWERCASEIf true, the IDs of ROLES will be lowercased, it has precedence against the default property.
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_ROLE_PATTERNConfigure the regex character class that identifies characters to be replaced with an underscore (_) in ROLE IDs. This takes precedence over the default property. This pattern must not be more permissive then the Orchestration Cluster's ID validation pattern
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_GROUP_LOWERCASEIf true, the IDs of GROUPS will be lowercased, it has precedence against the default property.
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_GROUP_PATTERNConfigure the regex character class that identifies characters to be replaced with an underscore (_) in GROUP IDs. This takes precedence over the default property. This pattern must not be more permissive then the Orchestration Cluster's ID validation pattern
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_USER_LOWERCASEIf true, the IDs of USERS will be lowercased, it has precedence against the default property.
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_USER_PATTERNConfigure the regex character class that identifies characters to be replaced with an underscore (_) in USER IDs. This takes precedence over the default property. This pattern must not be more permissive then the Orchestration Cluster's ID validation pattern
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_MAPPINGRULE_LOWERCASEIf true, the IDs of MAPPING RULES will be lowercased, it has precedence against the default property.
CAMUNDA_MIGRATION_IDENTITY_ENTITIES_MAPPINGRULE_PATTERNConfigure the regex character class that identifies characters to be replaced with an underscore (_) in MAPPING RULE IDs. This takes precedence over the default property. This pattern must not be more permissive then the Orchestration Cluster's ID validation pattern

Identity authorization and permission changes​

Camunda 8.8 introduces a new authorization model for Orchestration Cluster Identity. As a result, existing permissions must be reviewed to ensure continued access to APIs and web applications.

These changes apply after the upgrade, regardless of whether the Identity Migration Application is used.

Manual migration of roles and application permissions​

Permissions previously assigned through Management Identity roles and Management Identity applications must be recreated using Orchestration Cluster Identity authorizations.

You must:

  • Recreate required roles
  • Assign equivalent authorization records
  • Ensure access parity with the previous setup

The tables below map Management Identity permissions to their equivalent Orchestration Cluster authorizations.

Management Identity PermissionEquivalent Camunda Orchestration Cluster 8.8 Authorizations
ComponentPermissionResource TypeResource IDPermission(s)
OperatereadBATCH*READ
COMPONENTOperateACCESS
MESSAGE*READ
PROCESS_DEFINITION*READ_PROCESS_DEFINITION, READ_PROCESS_INSTANCE
DECISION_DEFINITION*READ_DECISION_DEFINITION, READ_DECISION_INSTANCE
DECISION_REQUIREMENTS_DEFINITION*READ
writeBATCH*CREATE, READ, UPDATE
COMPONENTOperateACCESS
RESOURCE*DELETE_FORM, DELETE_PROCESS, DELETE_DRD, DELETE_RESOURCE
PROCESS_DEFINITION*READ_PROCESS_DEFINITION, READ_PROCESS_INSTANCE, DELETE_PROCESS_INSTANCE, UPDATE_PROCESS_INSTANCE, MODIFY_PROCESS_INSTANCE CANCEL_PROCESS_INSTANCE
DECISION_DEFINITION*READ_DECISION_DEFINITION, READ_DECISION_INSTANCE, CREATE_DECISION_INSTANCE, DELETE_DECISION_INSTANCE
DECISION_REQUIREMENTS_DEFINITION*READ, UPDATE, DELETE
TasklistreadCOMPONENTTasklistACCESS
PROCESS_DEFINITION*READ_PROCESS_DEFINITION, READ_USER_TASK
writeCOMPONENTTasklistACCESS
PROCESS_DEFINITION*READ_PROCESS_DEFINITION, READ_USER_TASK, UPDATE_USER_TASK
IdentityreadAUTHORIZATIONS*READ
COMPONENTIdentityACCESS
GROUP*READ
ROLES*READ
TENANTS*READ
USERS*READ
read:usersCOMPONENTIdentityACCESS
USERS*READ
ROLES*READ
writeAUTHORIZATIONS*CREATE, READ, UPDATE, DELETE
COMPONENTIdentityACCESS
GROUP*CREATE, READ, UPDATE, DELETE
ROLES*CREATE, READ, UPDATE, DELETE
TENANTS*CREATE, READ, UPDATE, DELETE
USERS*READ

User role membership​

Recreate Management Identity role memberships using Orchestration Cluster Identity role management:

Assign users to a role

Groups​

Recreate groups setup in the Management Identity groups using Orchestration Cluster Identity group management:

Group management

Alternatively, you can use Bring your own Groups feature and recreate only the required Orchestration Cluster authorization records. This is the default behavior of the Identity Migration Application.

Resource authorizations​

Management Identity resource authorizations are replaced with a more granular Orchestration Cluster authorization management.

The table below lists equivalent Orchestration Cluster authorization records for former Management Identity resource authorizations.

(resource authorization table preserved exactly as in the original document)

Management Identity Resource AuthorizationsEquivalent Camunda Orchestration Cluster 8.8 Authorizations
Resource TypePermissionResource TypePermission(s)
PROCESSReadPROCESS_DEFINITIONREAD_PROCESS_DEFINITION, READ_PROCESS_INSTANCE
PROCESSDeleteRESOURCEDELETE_PROCESS
PROCESSUpdate process instancePROCESS_DEFINITIONUPDATE_PROCESS_INSTANCE
PROCESSDelete process instancePROCESS_DEFINITIONDELETE_PROCESS_INSTANCE
PROCESSStart process instancePROCESS_DEFINITIONCREATE_PROCESS_INSTANCE
DECISIONReadDECISION_DEFINITIONREAD_DECISION_DEFINITION, READ_DECISION_INSTANCE
DECISIONDeleteRESOURCEDELETE_DRD

Tenants​

Recreate Management Identity tenants using Orchestration Cluster Identity tenant management:

Tenant management

Mapping rules​

Recreate Management Identity mapping rules using Orchestration Cluster Identity mapping rule management:

Mapping rule management

API and web application permission migration​

With changes to the authorization system, access control for public APIs and component web applications has changed.

After upgrading to 8.8, review and update existing user and client permissions to:

  • keep access to APIs you still use (including deprecated component endpoints), and
  • keep the same visibility and actions in Operate and Tasklist as before the upgrade.

Migrate Operate V1 endpoint permissions​

If you still use Operate V1 endpoints, follow the instructions in the public API migration guides.

Migrate Operate and Tasklist access permissions​

UI permissions now control what users can see and what actions they can perform. Permissions are more granular (for example, a user can be limited to a specific process).

To keep the same access and behavior as in 8.7:

note

The authorization concept for batch operations in Operate has changed from user-based permissions to resource permissions.

After upgrading, users cannot see batch operations (including their own) unless they have read permissions for all batch operations.

For guidance on customizing access using the new model, see:

Camunda Exporter and harmonized data model​

Camunda 8.8 introduces the harmonized data model and the Camunda Exporter. This exporter replaces the legacy Elasticsearch and OpenSearch exporters.

For details about the new exporter and related changes, see the 8.8 announcements.

note

With the Camunda Exporter introduction, Camunda is compatible with Elasticsearch 8.16+ and no longer supports older Elasticsearch versions. See supported environments.

Ensure the importer backlog is drained​

To import data from 8.7, importers must first process existing data. Importers read from existing Zeebe indices, and when they detect data written by a newer version, they mark themselves as complete. The Camunda Exporter starts exporting only after the importers are complete.

important

Drain the importer backlog as much as possible before upgrading. If the backlog grows during the upgrade, web application data can become out of date. Zeebe may not be able to clean up data, which can increase disk usage and cause downtime.

You can validate importer latency using the following Prometheus metrics:

  • operate_import_time_seconds_sum
  • operate_import_time_seconds_count

For example, the following query shows import latency. If the result is in a range of seconds (ideally below 10 seconds), the system is typically ready to upgrade.

sum(rate(operate_import_time_seconds_sum{namespace=~"$namespace", partition=~"$partition", pod=~"$pod"}[$__rate_interval]))
/ sum(rate(operate_import_time_seconds_count{namespace=~"$namespace", partition=~"$partition", pod=~"$pod"}[$__rate_interval]))

Data migration​

Camunda 8.8 provides migration applications to preserve data integrity during the upgrade.

Migration applications are located in the camunda/bin/ directory. You can run them:

  • Locally, targeting the same Elasticsearch/OpenSearch instance
  • As standalone tools
  • Embedded in the standalone Camunda application (using Spring profiles)
  • As part of your deployment upgrade process (for example, Helm migration jobs)

Camunda also provides a data-migration binary that wraps all data migrations in a single application (excluding identity-migration).

Data migration requires a configured secondary storage. All migrations share the same base configuration, but you can adjust each migration as needed. Prometheus metrics for migration progress are exposed at the :9600/actuator/prometheus endpoint.

note

If you are upgrading with Helm, enable data migration in the Helm upgrade guide. See Data migration in the Helm upgrade guide.

This section describes advanced migration configuration and tuning options.

For details about each migration, see the sections below.

Scope​

Process migration unifies the previously separate operate-process and tasklist-process indices. To achieve this, it extracts Camunda Form–related data from deployments that was previously used only by Tasklist.

Depends on the Operate importer being completed.

Configuration​

Spring profile: process-migration

application.yaml:

camunda:
  migration:
    process:
      # How many process definitions are processed per round
      # Default 20
      batchSize: 5
      # How long the migration waits after the importer finishes before stopping
      # Default PT1M
      importerFinishedTimeout: PT1M
      # Timeout for the migration
      # Default PT2H
      timeout: PT2H
      # Retry properties (exponential backoff)
      retry:
        # How many times to retry failing operations before stopping the migration
        maxRetries: 5
        # Minimum retry delay applied to the backoff
        # Default PT1S
        minRetryDelay: PT10S
        # Maximum retry delay applied to the backoff
        # Default PT1M
        maxRetryDelay: PT1M

Exposed metrics​

  • camunda_migration_processes_migrated – Number of migrated processes so far
  • camunda_migration_processes_rounds – Number of migration rounds performed so far
  • camunda_migration_processes_round_time – Time taken to complete one migration round
  • camunda_migration_processes_single_process_time – Time taken to process a single process definition

Run migrations locally​

When running a migration application separately (for example, locally), provide access to its configuration.

For example:

SPRING_CONFIG_ADDITIONALLOCATION=/path/to/application.yaml ./camunda/bin/process-migration

Run migrations within the standalone Camunda application​

When running the standalone Camunda application, you can execute a migration within it by enabling the corresponding Spring profile.

Monitor migration completion​

In addition to the exposed Prometheus metrics, you can verify completion from logs. Example:

INFO io.camunda.migration.task.TaskMigrator - Task Migration completed successfully
INFO io.camunda.migration.process.ProcessMigrator - Process Migration completed
INFO io.camunda.migration.usagemetric.OperateMetricMigrator - Reindex task {id} completed successfully
INFO io.camunda.migration.usagemetric.TasklistMetricMigrator - Reindex task {id} completed successfully

Turn off importers after completion​

Importers are only required until migration completes. After migration is successful, you can turn them off.

note

To enable importers, set the following properties in application.yaml:

camunda:
  operate:
    importerEnabled: true
  tasklist:
    importerEnabled: true

To detect whether importers are complete, check the following indices:

  • tasklist-import-position-8.2.0_
  • operate-import-position-8.3.0_

If all entries show completed: true, importing is complete.

Alternatively, validate the following metrics:

  • operate_import_completed
  • tasklist_import_completed

Example query:

sum(tasklist_import_completed{namespace="$namespace"}) by (importPositionAlias)

metrics-import-complete

Orchestration Cluster REST API​

Removed deprecated OpenAPI objects​

In previous releases, entity keys were transitioned from integer (int64) to string types, while deprecated integer (int64) keys were still supported. As of Camunda 8.8, support for integer (int64) keys has been removed.

If you use API objects that still rely on integer (int64) keys, update them to use string keys and the application/json content type header before upgrading.

For more information, see the 8.7 API key attributes overview.

Streamlined variable OpenAPI objects​

The OpenAPI specification streamlines the objects used for variable filtering in search requests. The supported Camunda Java client handles these changes transparently. The affected endpoints are alpha APIs and were already marked as subject to change in earlier releases.

If you generate a custom REST client from the OpenAPI specification, note the following changes:

  • VariableValueFilterProperty replaces:

    • ProcessInstanceVariableFilterRequest
    • UserTaskVariableFilterRequest

  • For naming consistency, UserTaskVariableFilter replaces VariableUserTaskFilterRequest

Exported records​

USER_TASK records​

To support user task listeners, backward-incompatible changes were required for exported USER_TASK records.

assignee no longer provided in the CREATED event​

Previously, when a user task was activated with an assignee, the following events were exported:

  • CREATING with the assignee property set
  • CREATED with the assignee property set

In this case, the ASSIGNING and ASSIGNED events were not exported.

Starting with 8.8, the event sequence changes:

  • CREATING with the assignee property set
  • CREATED with assignee set to an empty string ("")
  • ASSIGNING with the assignee property set
  • ASSIGNED with the assignee property set

ASSIGNING renamed to CLAIMING for the CLAIM operation​

When claiming a user task in earlier versions, the following events were exported:

  • CLAIM
  • ASSIGNING
  • ASSIGNED

To distinguish claiming from assigning, a new CLAIMING intent has been introduced.

Starting with 8.8, claiming a user task produces:

  • CLAIM
  • CLAIMING
  • ASSIGNED

For assignment operations, the following events are still exported:

  • ASSIGN
  • ASSIGNING
  • ASSIGNED

Zeebe record types​

With the introduction of the Camunda Exporter, the Elasticsearch and OpenSearch exporters no longer export all Zeebe record types by default.

The following record types continue to be exported by default:

  • DEPLOYMENT
  • PROCESS
  • PROCESS_INSTANCE
  • VARIABLE
  • USER_TASK
  • INCIDENT
  • JOB

To export additional record types, configure includeEnabledRecords for:

Exporter deletion​

Removing exporter configuration no longer deletes the exporter from the system. Instead, the exporter enters a blocked state to prevent accidental data loss caused by manual or unintended configuration changes.

To permanently remove an exporter, use the Exporters API.

Connectors​

Email connector​

Starting with Camunda 8.8, angle brackets (< and >) are no longer removed from the messageId field. If you rely on the previous behavior, update your connector logic accordingly.

Logging​

Default configuration​

The default logging configuration is included inline for reference. For advanced settings, see the logging configuration documentation.

Rolling file appender​

The RollingFile appender is disabled by default.

To enable it, set the appropriate environment variable for each component:

ZEEBE_LOG_APPENDER=RollingFile

Other supported component variables:

  • OPERATE_LOG_APPENDER
  • IDENTITY_LOG_APPENDER
  • TASKLIST_LOG_APPENDER

Use the variable that corresponds to the component you are configuring.

Pattern layout changes​

The default log pattern has changed.

Previous pattern:

[%d{yyyy-MM-dd HH:mm:ss.SSS}] [%t] %notEmpty{[%X] }%-5level%n\t%logger{36} - %msg%n

New pattern:

%d{HH:mm:ss.SSS} [%t] %notEmpty{[%X] }%-5level%logger{1.1.1.*} - %msg%n
AspectPrevious patternNew pattern
TimestampFull date and timeTime only
Logger nameUp to 36 charactersPackage initials + full class name
Newline after levelYesNo
Tab before loggerYesNo

Elasticsearch​

Starting with Camunda 8.8, the default replica count for Elasticsearch and OpenSearch indices changes from 0 to 1. This ensures that Camunda is not blocked if a node becomes temporarily unavailable.

If you already override this value, no action is required.

Throughout this section, references to Elasticsearch (ES) also apply to OpenSearch (OS).

Single-node cluster​

If the cluster has only one node, a replica count of 1 results in a yellow cluster state because replica shards cannot be assigned.

To resolve this:

If you installed Elasticsearch using the Camunda Helm chart, the default master.replicaCount is 3. For other setups, you can apply the same logic by setting elasticsearch.master.replicaCount.

Multi-node cluster​

Starting with Camunda 8.8, the default replica count for Camunda indices in Elasticsearch and OpenSearch is 1. If your cluster previously used a replica count of 0, disk usage will roughly double.

To ensure the cluster can reach a green status, provision disk capacity of at least 2.5x the previously used storage. This accounts for shard watermarks, operational overhead, and future growth.

For example:

  • In 8.7, node disk usage is:

    • 30 GB / 50 GB
    • 35 GB / 50 GB
    • 40 GB / 50 GB

  • The most used node consumes 40 GB

  • To accommodate replicas, resize all disks to at least 100 GB (40 × 2.5)

Resize Elasticsearch disk​

If the current disk size cannot accommodate replicas, increase disk capacity. Whether a Persistent Volume Claim (PVC) can be expanded depends on the underlying StorageClass.

For Kubernetes-based deployments, see:

For managed services, see:

Roll back​

If you encounter issues after the upgrade and replica increase, revert the replica count to 0 and restart Zeebe. When Zeebe restarts, it updates the index settings accordingly.

Set one of the following:

  • application.yaml:

    camunda:
      database:
        index:
          numberOfReplicas: 0

  • Environment variable:

    CAMUNDA_DATABASE_INDEX_NUMBER_OF_REPLICAS=0

Web Modeler​

Cluster configuration​

Removed authentication methods​

The previously deprecated authentication methods OAUTH and CLIENT_CREDENTIALS are no longer supported. If your Web Modeler installation still uses one of these methods, update the cluster configuration:

  • Replace OAUTH with BEARER_TOKEN (the value was renamed).
  • Replace CLIENT_CREDENTIALS with BEARER_TOKEN if:
    • The cluster is upgraded to 8.8, and
    • The cluster uses OIDC authentication, and
    • Web Modeler and the cluster use the same identity provider.

The previous requirement for the identity provider to support access tokens with multiple audiences no longer applies. However, you must ensure the cluster accepts Web Modeler’s token audience by including it in the configured list of audiences. See Configure the OIDC connection details.

Changed configuration options​

Available configuration options depend on the cluster version. For clusters running 8.8, additional configuration options are required.

If your existing configuration references a cluster that was upgraded from an earlier version, update it as follows:

  • Change CAMUNDA_MODELER_CLUSTERS_*_URL_ZEEBE_GRPC to CAMUNDA_MODELER_CLUSTERS_*_URL_GRPC
  • Change CAMUNDA_MODELER_CLUSTERS_*_URL_ZEEBE_REST to CAMUNDA_MODELER_CLUSTERS_*_URL_REST
  • Add CAMUNDA_MODELER_CLUSTERS_*_URL_WEBAPP
  • Add CAMUNDA_MODELER_CLUSTERS_*_AUTHORIZATIONS_ENABLED
  • Remove CAMUNDA_MODELER_CLUSTERS_*_URL_OPERATE
  • Remove CAMUNDA_MODELER_CLUSTERS_*_URL_TASKLIST

For more information, see Additional configuration for cluster versions ≥ 8.8.