Prepare for upgrade
Learn how to prepare for a successful upgrade to Camunda 8.8 by evaluating your infrastructure, understanding operational changes, and choosing the best upgrade strategy for your environment.
Step 1: Evaluate your current setup
First, you should evaluate your current setup:
| Area | Details |
|---|---|
| Platform version | Direct upgrades are only supported from 8.7.x to 8.8.x. You must upgrade to the latest 8.7 patch before upgrading to 8.8. |
| Component version alignment | Orchestration components such as Zeebe, Operate, Tasklist, and Identity must run the same version. |
| 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.
Start with the high-level overview what's new in Camunda 8.8.
| Area | What's changed | Impact | Description |
| Orchestration Cluster | Zeebe, Operate, Tasklist, and Identity are consolidated into a single Orchestration cluster. | Low | Unified scaling, fewer components to operate, and a different resource profile for the orchestration runtime. |
| Orchestration Cluster API | A new unified REST API for an Orchestration cluster. | Medium | Operate and Tasklist (V1) APIs are deprecated and should be replaced by the Orchestration Cluster API. |
| Data and exporters | Unified exporter architecture and unified data schema. | Medium |
|
| Unified components configuration | A new unified configuration with a shared YAML schema across Orchestration cluster components. | Breaking changes | Replacement of deprecated configuration properties to their successors. Specific properties have breaking changes that require adaptation. |
| Optimize | Performs a startup data migration. | Low | Requires downtime during startup data migration. You need to plan a maintenance window. |
| Identity, authentication, and authorization | Orchestration Cluster provides Identity and Access Management (IAM) inside a cluster. | 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 | Impact | Description |
| Access control and permissions | Low | The new authorization model introduces fine-grained access control for Orchestration Cluster resources, replacing the previous model. Run the Identity migration scripts during the upgrade to migrate authorizations. |
| User groups, roles, tenants, and mapping rules | Low | Now managed within Orchestration Cluster Identity, replacing the previous Management Identity setup. Run the Identity migration scripts during the upgrade to migrate entities. |
| User task authorizations | Medium | User task access restrictions only apply to the Tasklist v1 API. After switching to the v2 API with Tasklist, user task access restrictions do not apply. |
| Identity via Keycloak | Medium | If managing Keycloak internally, verify required database schema updates. Confirm supported Keycloak versions in the environment matrix. |
| User storage in Elasticsearch/OpenSearch for Operate or Tasklist | Breaking changes | No longer supported. You must transition to using Basic authentication and re-create users in Orchestration Cluster Identity. |
| LDAP authentication for Operate or Tasklist | Breaking changes | No longer supported. You must transition to OIDC or Basic Authentication. |
Learn more about all 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. |
| CPU/Memory | Consolidated Zeebe StatefulSet shares limits. | Measure current usage; test with load generator |
| Storage | Same or higher IOPS as 8.7. | Check space for temporary migration file. |
You should run a load test that simulates real production traffic, as component consolidation changes resource consumption. This ensures your cluster sizing is appropriate before you upgrade your production environment.
Step 4. Create an upgrade timeline
Create and define the timeline for your upgrade, taking into account the duration of upgrade phases.
| Phase | Typical duration | Downtime |
|---|---|---|
| Pre-upgrade preparation | 1–2 weeks | No |
| Cluster update | 1–4 hours | Depends on data migration size |
| Validation and tuning | 1–2 days | No |
Camunda advises you to document your backup and rollback procedures for each phase.
Next steps
Once you have completed your preparation plan, continue to:
- Review your plan with your operations, security, and development teams.
- Schedule the maintenance window and notify all stakeholders.
- Continue with the perform an upgrade guide.
For more background, see the component upgrade guide and version-specific documentation.