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.

Area	What's changed / Action required	Impact
Helm chart: Secret configuration	Deprecated secret keys removed in 8.9. If your values.yaml uses old key paths (for example, global.license.key, *.existingSecret at legacy paths), update them to the new *.secret.existingSecret pattern before upgrading. Additionally, global.secrets.autoGenerated is removed. All secrets must be explicitly provided. For details, see Helm chart: Deprecated secret keys removed and Secret management.	Action required
Helm chart: document-store default	The Elasticsearch subchart is no longer enabled by default. If you use Elasticsearch, explicitly set global.elasticsearch.enabled: true and elasticsearch.enabled: true in your values file. You must also set orchestration.data.secondaryStorage.type explicitly (no default), whether you use Elasticsearch, OpenSearch, or RDBMS.	Action required
Helm chart: REST port	The default HTTP port for the Orchestration Cluster changed from 8090 to 8080. If you have hardcoded port references in network policies, Ingress rules, or monitoring, update them.	Check
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.	If customized
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

info

For a complete list of changes, see What's new in Camunda 8.9.

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:

• Upgrade Helm chart
• Manual upgrade

tip

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