Prepare for upgrade

This guide is a starting point to get high level overview of preparation for an upgrade to Camunda 8.8 Self-Managed: assess your infrastructure, review operational changes, and choose an upgrade strategy appropriate for your environment.

Step 1: Evaluate your current setup

Check your current setup and make sure you are ready to upgrade.

Area	Description and actions
Camunda version	Direct upgrades are only supported from 8.7.x to 8.8.x. You must upgrade all Camunda applications to it latest 8.7.x patch before upgrading to 8.8.
Configuration customizations	Identify non-default parameters and values in configuration files, ingress rules, external Elasticsearch/OpenSearch configurations, and custom exporters.

Step 2: Assess Camunda 8.8 changes and impact

Review and make sure you understand the platform-level changes between Camunda 8.7 and 8.8. Understanding these highlights helps you plan your upgrade and anticipate operational impacts.

tip

Start with the high-level overview what's new in Camunda 8.8.

Area	What's changed	Impact
Orchestration Cluster	Zeebe, Operate, Tasklist, and Identity are consolidated into a single Orchestration cluster.	Low
Orchestration Cluster API	Introduced a new unified REST API for an Orchestration cluster. Operate and Tasklist (V1) APIs are deprecated and should be replaced by the Orchestration Cluster API. For more information, see the blog post upcoming API Changes in Camunda 8.	Medium
Data and exporters	Introduced unified exporter architecture and unified data schema. Requires temporary rebalancing of indices and additional disk space while data is moved to unified indices. Dedicated data retention configurations per application (Zeebe, Tasklist, Operate) are no longer supported. If Tasklist data is present, an additional data migration is required - process application migration utilities are offered for this.	Medium
Unified components configuration	Introduced a new unified configuration with a shared YAML schema across Orchestration cluster components. To learn more, see Camunda 8.8 property changes.	Breaking changes
Elasticsearch/OpenSearch: shared-only	Dedicated Elasticsearch or OpenSearch clusters per application are no longer supported. All Orchestration components must use a single, shared cluster.	Breaking changes
Zeebe Gateway	Tenant-providing interceptors are not supported and should be replaced with built-in tenant management.	Breaking changes
Tasklist UI mode	Tasklist UI supports two modes: V1 (that uses the deprecated Tasklist API) and V2 (that uses the Orchestration Cluster API). Tasklist UI in V1 API mode is available as a configuration option, which allows you to access legacy features during the transition. We recommend planning your migration to the V2 API to take advantage of all the latest features. To learn more about the differences between the V1 and V2 modes, see the Tasklist API versions documentation.	Low
Optimize	Performs a startup data migration that requires downtime during startup data migration. You must plan a maintenance window.	Low
Identity, authentication, and authorization	Orchestration Cluster provides Identity and Access Management (IAM) inside a cluster. To learn more, see Identity, authentication, and authorization below.

Identity, authentication, and authorization

Orchestration Cluster Identity handles authentication and authorization for Orchestration Cluster components and resources.

The following table provides a high-level overview of the impact of these changes:

Area	Description	Impact
Access control and permissions	The new authorization model introduces fine-grained access control for Orchestration Cluster resources, replacing the previous model. Camunda provides the Identity migration application to help migrate data from 8.7 to 8.8. Helm charts run Identity migration application as part of the upgrade process. If you are using custom deployment, please review Helm Charts Migration Jobs for reference.	Low
User groups, roles, tenants, and mapping rules	This is now managed within Orchestration Cluster Identity, replacing the previous Management Identity setup. Camunda provides the Identity migration application to help migrate data from 8.7 to 8.8. Helm charts run Identity migration application as part of the upgrade process. If you are using a custom deployment, review Helm Charts Migration Jobs for reference.	Low
User task authorizations	The Tasklist V1 API supports User task access restrictions. After switching to the Tasklist V2 API, user task access restrictions do not apply.	Medium
Identity via Keycloak	If managing Keycloak internally, you must verify the required database schema updates. Confirm supported Keycloak versions in the environment matrix.	High
User storage in Elasticsearch/OpenSearch for Operate or Tasklist	This is no longer supported. You must transition to using Basic Authentication and recreate users in Orchestration Cluster Identity. See the documentation for Tasklist authentication and Operate authentication.	Breaking changes
LDAP authentication for Operate or Tasklist	This is no longer supported. You must transition to use OIDC or Basic Authentication.	Breaking changes

info

Learn more about the Identity 8.8 changes in the Identity section of what's new in Camunda 8.8.

Step 3. Check infrastructure compatibility

Check and verify your infrastructure compatibility for Camunda 8.8.

Area	8.8 requirement	Action
Elasticsearch/OpenSearch	Elasticsearch ≥ 8.16 (OpenSearch TBD).	Upgrade the cluster to the new version. Check the supported environments matrix to confirm the minimum version.
CPU/Memory	Consolidated Zeebe StatefulSet shares limits.	Measure current usage. Test with a load generator.
Storage	Same or higher IOPS as 8.7.	Check there is required space for temporary migration file.

Plan a performance test

You should run a load test that simulates real production traffic, as component consolidation changes resource consumption. See the sizing guidelines and benchmarking recommendations to determine appropriate cluster sizing before you upgrade your production environment.

Next steps

Once you have confirmed you are ready to upgrade and taken any actions required, proceed to the upgrade.

Perform an upgrade

tip

For more information, see the component upgrade guide and version-specific documentation.

Useful resources

• Supported environments
• 8.8 release notes
• Helm chart 8.7 to 8.8 technical details
• Component upgrade guide