The following sections explain which adjustments must be made to migrate from Camunda 8.2.x to 8.3.x for each component.
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
The update from
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.
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.
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.
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_EXCEEDEDmessages 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:CREATEDevent are no longer available. Custom exporters using the resources from this event must be modified to get them from the
Process:CREATEDevent for BPMN models and the
DecisionRequirements:CREATEDevent for DMN models.
DeploymentDistributionvalue type is deprecated. Custom exporters consuming distribution records must be modified to consume the new
CommandDistributionrecord instead. Intents for this record are:
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.
/metricsendpoint is now
/metricsendpoint is now
/healthendpoint is now
/startupendpoint is now
/liveendpoint is now
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
You can read more about the new error handling in the FEEL documentation.
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
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
Within an expression, you could use the
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
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
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
- In application.yaml
- Or through the environment variables:
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.
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
- Zeebe, and Operate no longer support AWS OpenSearch
- Identity, and Web Modeler now require Keycloak
22.x. Please ensure to update your Keycloak environment when migrating to Camunda
- Optimize now requires OpenJDK
Please see supported environments for more a full overview of Camunda environment requirements.