Update 8.2 to 8.3

Intermediate

The following sections explain which adjustments must be made to migrate from Camunda 8.2.x to 8.3.x for each component.

caution

We identified some bugs in 8.3.0 that could prevent the migration from succeeding. These are resolved in the 8.3.1 patch. We recommend updating to 8.3.1 directly.

info

The update from 8.2.x to 8.3.x performs a migration for nearly all entities stored in Operate, Tasklist, and Optimize to support multi-tenancy. Therefore, migration may take longer.

Helm chart - Breaking Changes

For more details about the breaking changes in the Helm chart, check the upgrade page for v8.3.0.

note

Camunda is compatible with Elasticsearch 8.8+ (see supported environments) which you can download here.

Zeebe - Breaking Changes

Zeebe Docker image now runs with unprivileged user by default

The default user in the Zeebe Docker image changed from root to an unprivileged user with the UID 1000. This was done to provide stronger compliance with the OWASP recommendations on Docker Security.

caution

If you experience permission errors on data or log volumes access when updating to 8.3.0, you may need to make sure mounted volumes and existing files are writable by this user.

In a kubernetes setup this can be done by setting the fsGroup to 1000. Newer versions of the Camunda Helm chart have this is set by default

For more details and alternatives please refer to the Camunda Helm Update instructions.

caution

When upgrading to 8.3, Zeebe runs a migration. Depending on the amount of active element instances in the cluster, this migration may cause a longer startup time than usual. While this migration is running, users may experience:

• DEADLINE_EXCEEDED messages in job workers.
• Unhealthy partitions in the Zeebe cluster.
  • For SaaS users, this marks the entire Zeebe cluster as unhealthy.
• No processing happens during the migration.

Changes to exported records

• Resources in the Deployment:CREATED event are no longer available. Custom exporters using the resources from this event must be modified to get them from the Process:CREATED event for BPMN models and the DecisionRequirements:CREATED event for DMN models.
• The DeploymentDistribution value type is deprecated. Custom exporters consuming distribution records must be modified to consume the new CommandDistribution record instead. Intents for this record are:
  • STARTED (event)
  • DISTRIBUTING (event)
  • ACKNOWLEDGE (command)
  • ACKNOWLEDGED (event)
  • FINISHED (event)

Change in monitoring endpoints

There were some changes to the monitoring endpoints of Zeebe, both for the gateway and the broker. All of these were existing redirects to the new endpoints, so their format is left unchanged; only the redirects have been removed.

You may have to change your Kubernetes health probes or metrics scraping endpoints to accommodate the new ones. Note that if you're deploying with the Helm charts, or are using Camunda 8 SaaS, you do not need to do anything.

Broker

• The /metrics endpoint is now /actuator/prometheus

Gateway

• The /metrics endpoint is now /actuator/prometheus
• The /health endpoint is now /actuator/health
• The /startup endpoint is now /actuator/health/startup
• The /live endpoint is now /actuator/health/liveness

New error handling of expressions

FEEL expressions are used in BPMN processes for properties and in DMN decisions. We changed how errors are handled on evaluating an expression. Previously, an expression might fail and caused an incident for a process instance because of a missing variable or a missing context entry. Now, the expression will be evaluated successfully and return null in these cases.

You can read more about the new error handling in the FEEL documentation.

caution

The new error handling may affect new and already deployed processes and decisions. As a result, a process instance might create no incidents anymore compared to before. You should take care especially on input and output variable mappings because a missing variable results in null and the process instance continues with the null value.

Other BPMN properties that require a specific value type are not affected, for example, a condition on an exclusive gateway. If an expression results in null, an incident will be created because of type mismatch.

If you have a strong need to verify that a value is not null, you can use an assertion to restore the previous behavior and force the creation of an incident.

Change in the function is defined()

Within an expression, you could use the function is defined() to check if a variable exists. As part of the new error handling of expressions, the semantics of the function changed.

In previous versions, the function returned true if the given variable did exist, even if its value was null. The function returned false if the variable didn't exist.

With the new version, the behavior changed if the variable value is null. The function returns true if the variable exists and its value is not null. It returns false if the variable doesn't exist or its value is null.

Multi-tenancy

Zeebe migration

Updating may take longer if the experimental consistency checks enabled. If the duration of the downtime needs to be shortened, set the following properties to false while migrating Zeebe to 8.3.0:

• In application.yaml
  • Broker: zeebe.broker.experimental.consistencyChecks.enablePreconditions
  • Broker: zeebe.broker.experimental.consistencyChecks.enableForeignKeyChecks
• Or through the environment variables:
  • Broker: ZEEBE_BROKER_EXPERIMENTAL_CONSISTENCYCHECKS_ENABLEPRECONDITIONS
  • Broker: ZEEBE_BROKER_EXPERIMENTAL_CONSISTENCYCHECKS_ENABLEFOREIGNKEYCHECKS

Operate migration

Updating may take longer as a majority of Operate data must be re-indexed in Elasticsearch to add the tenantId field. To speed up data migration during version updates, consider adding more resources to your Elasticsearch cluster.

Accessing existing data

Once multi-tenancy is enabled, all existing data is owned by the <default> tenant. To continue to guarantee access to these data, users should be assigned to the <default> tenant in Identity.

Connectors

[Breaking changes!]

The HTTP Webhook Connector no longer returns a response body by default. If you want to return a response body, you must explicitly define a response body expression. See the usage guide or the Webhook Connector documentation for more details.

Changes in supported environments

• Zeebe, Operate, Tasklist, and Optimize now require Elasticsearch 8.8+. Please ensure to update your Elasticsearch environment when migrating to Camunda 8.3.x.
• Zeebe, and Operate no longer support AWS OpenSearch 1.3.x.
• Identity, and Web Modeler now require Keycloak 21.x or 22.x. Please ensure to update your Keycloak environment when migrating to Camunda 8.3.x.
• Optimize now requires OpenJDK 17+.

Please see supported environments for more a full overview of Camunda environment requirements.