Prepare for upgrade
Prepare your Self-Managed environment for an upgrade to Camunda 8.8. Use this guide to confirm upgrade eligibility, understand platform-level changes, and identify actions you may need to take before running an upgrade.
Evaluate your current environment
Before upgrading, verify that your current installation meets the minimum requirements.
| Area | What to check |
|---|---|
| Camunda version | Direct upgrades to 8.8 are supported only from the latest 8.7.x patch. If you are running an earlier version, first upgrade to 8.7. See Upgrading from an earlier version. |
| Environment support | Ensure your platform and dependencies are supported in 8.8. See Supported environments. |
| Customizations | Identify non-default values in Helm values, application YAML files, Ingress configuration, exporters, and Elasticsearch/OpenSearch setup. |
Review platform changes in Camunda 8.8
Camunda 8.8 introduces architectural and behavioral changes that may require configuration updates, data migration, or operational planning. Review the following areas to understand their impact on your environment.
| Area | What's changed | Impact |
| Orchestration Cluster | Zeebe, Operate, Tasklist, and Identity are consolidated into a single Orchestration cluster. | Low |
| Tasklist UI mode | Tasklist UI supports two modes: V1 (deprecated Tasklist API) and V2 (Orchestration Cluster API). V1 remains available as a temporary option for legacy features. Migration to V2 is recommended to access current and future functionality. For more information, see Tasklist API versions. | Low |
| Optimize | Performs a startup data migration that requires downtime during startup data migration. You must plan a maintenance window. | Low |
| Identity | The HTTP port of the identity pod changed from 8080 to 8084. If you have restrictive network policies, verify that the port is whitelisted. | 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 a unified exporter architecture and data schema. Depending on your configuration, this may require prefix migration. Dedicated data retention settings per component are no longer supported. A data migration is required. For more information, see prefix migration and data migration. | Medium |
| Unified components configuration | Introduced a new unified configuration with a shared YAML schema across Orchestration cluster components. For more information, see Property changes in Camunda 8.8. | 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 |
| Zeebe Java Client/Spring SDK <=8.7.15 with REST API enabled | These clients are incompatible with 8.8 when REST API support is enabled. For more information, see Orchestration Cluster: Zeebe Java Client <=8.7.15 with REST API enabled is incompatible with 8.8 | Breaking changes |
For a complete list of changes, see What’s new in Camunda 8.8.
Identity, authentication, and authorization
Orchestration Cluster Identity handles authentication and authorization for Orchestration Cluster components and resources. Orchestration Cluster provides Identity and Access Management (IAM) inside a cluster.
Authorization changes and migration
Camunda 8.8 introduces a new authorization model for Orchestration Cluster resources.
- Existing authorization data must be migrated from 8.7 to 8.8.
- Camunda provides an Identity migration application to perform this migration.
- Helm-based upgrades run the migration automatically as part of the upgrade process.
- For custom deployments, review the Helm migration jobs as a reference for running the migration manually.
For more information, see Orchestration Cluster authorization
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.
User management and authentication changes
| Area | Description | Impact |
| User groups, roles, tenants, and mapping rules | Management moves to Orchestration Cluster Identity, replacing Management Identity. Existing data must be migrated. | Low |
| User task authorizations | The Tasklist V1 API supports User task access restrictions. These restrictions do not apply when using the Tasklist V2 API. | Medium |
| Identity via Keycloak | If you manage Keycloak internally, verify required database schema updates and confirm supported versions in supported environments. | 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. For more information, see Tasklist authentication and Operate authentication. | Breaking changes |
| LDAP authentication for Operate or Tasklist | This is no longer supported. You must transition to OIDC or Basic Authentication. | Breaking changes |
For more information about the Identity 8.8 changes, see Identity, authentication, and authorization in what's new in Camunda 8.8.
Verify infrastructure compatibility
Review your infrastructure to confirm compatibility with Camunda 8.8.
| Area | 8.8 requirement | Action |
|---|---|---|
| Elasticsearch/OpenSearch | Elasticsearch 8.16+, OpenSearch 2.17+. | 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. |
Component consolidation in 8.8 changes resource consumption patterns. Before upgrading production, run a load test that simulates real traffic and validate CPU, memory, and storage behavior.
Next steps
Once you have completed all preparation steps and confirmed your environment is ready, proceed with the upgrade method that matches your deployment:
For more information on component-specific changes, see the component upgrade guide and version-specific documentation.