Prepare for upgrade
Prepare your Self-Managed environment for an upgrade to Camunda 8.9.
About
Use this guide to confirm upgrade eligibility, understand platform-level changes, and identify actions you may need to take before running an upgrade.
All Camunda upgrades must follow the required upgrade procedure: upgrade one minor version at a time and never skip minors. For best stability and fix coverage, use the latest available patch in each minor before and after the minor upgrade.
See version compatibility checks.
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.9 are supported from 8.8.x. If you are running an earlier version, first upgrade to 8.8. For best stability and fix coverage, use the latest available 8.8.x patch before upgrading. See upgrading from an earlier version. |
| Environment support | Ensure your platform and dependencies are supported in 8.9. See supported environments. |
| Customizations | Identify non-default values in Helm values, application YAML files, Ingress configuration, exporters, and secondary storage setup (for example, Elasticsearch/OpenSearch or RDBMS). |
Review pre-upgrade actions required for Camunda 8.9
This section lists actions you must complete or review before upgrading to Camunda 8.9.
| Impact | Area | What's changed / Action required |
|---|---|---|
| Action required | Helm chart: Secret configuration | Deprecated secret keys are removed in 8.9.
|
| Action required | Helm chart: document-store default | The Elasticsearch subchart is no longer enabled by default.
|
| Check | Helm chart: REST port | The default HTTP port for the Orchestration Cluster changed from 8090 to 8080. Check and update any hardcoded port references in network policies, Ingress rules, or monitoring. |
| If customized | Web Modeler: Removed webapp component | Web Modeler's separate webapp component has been removed, and its functionality is now integrated into the restapi component. If you use custom configuration settings for the webapp or replace the restapi configuration using webModeler.restapi.configuration, you need to update your configuration. See the component upgrade guide. |
| If customized | Web Modeler: Logging framework | Web Modeler restapi now uses Apache Log4j 2 instead of Logback. If you have a custom Logback configuration, migrate it before upgrading. See the Log4j migration guide. |
| If customized | Web Modeler: Embedded web server | Web Modeler now uses Apache Tomcat instead of Undertow. If you have custom Undertow configuration (server.undertow.*), migrate it to Tomcat equivalents. See the component upgrade guide for a property mapping table. |
| Recommended | Helm chart: TLS secret pattern | Legacy TLS secret configuration (*.tls.existingSecret) is deprecated. Migrate to *.tls.secret.existingSecret. The legacy keys still work in 8.9. |
| Recommended | Helm chart: Bitnami subcharts | The Bitnami-based subcharts (identityPostgresql, identityKeycloak, webModelerPostgresql, elasticsearch) are deprecated in 8.9 and will be removed in 8.10. Plan migration to externally managed services. |
| Recommended | Helm chart: secondary storage global config | global.elasticsearch.* and global.opensearch.* are deprecated in 8.9 and will be removed in 8.10. Migrate to orchestration.data.secondaryStorage.elasticsearch/opensearch.* and optimize.database.elasticsearch/opensearch.*. Legacy keys still work in 8.9. |
| Recommended | Helm chart: Orchestration profile | orchestration.profiles.identity is deprecated and renamed to orchestration.profiles.admin. The chart auto-migrates the old key with a deprecation warning. Update your values file to use the new key. |
| Recommended | Helm chart: Keycloak auth secret | global.identity.keycloak.auth.existingSecret and existingSecretKey are deprecated. Migrate to global.identity.keycloak.auth.secret.existingSecret and existingSecretKey. Legacy keys still work in 8.9 via normalizers. See Secret management. |
For a full list of changes, see the 8.9 release announcements and release notes.
Verify infrastructure compatibility
Review your infrastructure to confirm compatibility with Camunda 8.9.
| Area | 8.9 requirement | Action |
|---|---|---|
| Secondary storage (Elasticsearch/OpenSearch) | Elasticsearch 8.19+, OpenSearch 2.19+. Elasticsearch 9.2+ and OpenSearch 3.4+ now supported. | Upgrade the cluster to the minimum version. Check the supported environments matrix to confirm compatibility. |
| Secondary storage (RDBMS) | Supported vendor and version required for your selected component set. | Check the RDBMS support policy and confirm any component-specific limitations before upgrading. |
| CPU/Memory | Same consolidated Orchestration StatefulSet as 8.8. | No new requirements compared to 8.8. |
| Storage | Same or higher IOPS as 8.8. | No change from 8.8. |
Next steps
Once you have confirmed upgrade eligibility and completed any required preparation steps, 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.