Upgrade Camunda components from 8.8 to 8.9
This page is a work in progress for Camunda 8.9 and will be updated as upgrade requirements are finalized.
Review component-level actions that may be required when upgrading a Camunda 8 Self-Managed deployment from 8.8.x to 8.9.x.
About
Use this page with the deployment upgrade guide for your environment. Start with the Upgrade Camunda 8 overview, then apply any component-specific steps that match your setup.
Connectors
Default secret provider prefix change (breaking)
Starting with Camunda 8.9, the environment-based secret provider uses SECRET_ as the default prefix. Only environment variables starting with the configured prefix are available as connector secrets.
- Before 8.9: With no prefix configured, all environment variables were accessible as connector secrets.
- From 8.9: Only environment variables starting with
SECRET_(or your configured prefix) are considered connector secrets.
This is a breaking change for Self-Managed deployments that relied on unprefixed environment variables as secrets. Existing, unprefixed secrets will no longer resolve after upgrading.
Choose one of the following options:
- Use the default secure prefix: Update your connector secret environment variables to use the
SECRET_prefix, and ensure the prefix is explicitly set:camunda.connector.secret-provider.environment.prefix=SECRET_ - Configure a custom prefix: Configure your own prefix via:
- Java property:
camunda.connector.secret-provider.environment.prefix - Environment variable:
CAMUNDA_CONNECTOR_SECRET_PROVIDER_ENVIRONMENT_PREFIX
- Java property:
- Restore the previous behavior (unsafe): To allow all environment variables as secrets as in earlier versions, set the prefix to an empty value:
This mode logs a warning, and Camunda does not recommend it for production environments.
camunda.connector.secret-provider.environment.prefix=
For full configuration details, see connector secrets configuration.
Optimize
Exporter filters and Optimize upgrade safety
With exporter-side filters in Camunda 8.9 and later, you can limit the records exported to Optimize. However, this can affect Optimize imports when Optimize uses the legacy Elasticsearch or OpenSearch exporter as its data source.
Do not change exporter filters during upgrade or migration windows. While upgrading components or running importer-based migrations, keep the exporter configuration stable.
Changing which records are exported (for example, by filtering variables or processes) during an Optimize import can affect its sequence-based import logic and lead to gaps or inconsistencies in reports.
Treat enabling exporter filters on an existing cluster as a data-model change. When you start exporting only a subset of records for Optimize, the contents of the zeebe-record-* indices that Optimize reads effectively change. For production environments, follow the full re-import guidance in the Optimize system configuration to realign Optimize with the filtered data set rather than relying on incremental imports alone.
For details on:
- What exporter filters are and how to configure them, see:
- When to use exporter filters for Optimize and how to perform a safe re-import, see:
Exported records
PROCESS_INSTANCE_CREATION records
Variables no longer included in the CREATED event
Previously, exported zeebe-record-process-instance-creation* records with intent CREATED contained variables. Starting with 8.9, these records no longer include variables.
If you rely on variables from this event in a custom exporter or integration, use zeebe-record-variable* records with intent CREATED instead. These variable records are exported during process instance creation and contain the same variable data.
Web Modeler
Migrate webapp configuration
In Web Modeler 8.9, the separate webapp component has been removed, and its functionality is now integrated into the restapi component.
This means that the configuration values listed in the subsections below, which were previously expected by the webapp, now need to be configured for the restapi.
No action is required if you use the recommended Helm chart installation method without any custom configuration.
The restapi is already configured correctly using the values provided for the Helm chart parameters.
In the following cases, you need to update the application configuration for Web Modeler manually:
-
If you're using custom configuration settings for the
webapp, for example, for feature flags or a proxy server, migrate the settings to therestapias described below. -
If you've completely replaced the
restapiconfiguration using the Helm chart'swebModeler.restapi.configurationoption, add the properties listed below to therestapiconfiguration. You at least need to add the required options that don't have a default value. Otherwise, the application will fail to start.tipConsider switching to
webModeler.restapi.extraConfiguration, with which you can add or override settings without replacing the default configuration entirely.
You can set the configuration values for the restapi either as environment variables or application properties.
For custom settings that you do not migrate from the webapp to the restapi, Web Modeler will fall back to the default value (if applicable) after the upgrade to 8.9.
This might cause unexpected behavior. Make sure to check which settings you have customized that need to be migrated.
OAuth2 configuration
If you've set custom values for any of the settings below in the webapp configuration, add them to the restapi configuration instead.
Refer to the configuration page for details on these properties.
| Environment variable | Application property | Required? | Default value |
|---|---|---|---|
OAUTH2_CLIENT_ID | camunda.modeler.oauth2.client-id | yes | - |
OAUTH2_CLIENT_FETCH_REQUEST_CREDENTIALS | camunda.modeler.oauth2.client.fetch-request-credentials | no | - |
CAMUNDA_IDENTITY_USERNAMECLAIM | camunda.modeler.oauth2.token.username-claim | no | name |
WebSocket client configuration
If you've set custom values for the WebSocket/Pusher client settings in the webapp configuration, add them to the restapi configuration instead.
Refer to the configuration page for details on these properties.
| Environment variable | Application property | Required? | Default value |
|---|---|---|---|
CLIENT_PUSHER_HOST | camunda.modeler.pusher.client.host | yes | - |
CLIENT_PUSHER_PORT | camunda.modeler.pusher.client.port | no | 80 |
CLIENT_PUSHER_PATH | camunda.modeler.pusher.client.path | no | / |
CLIENT_PUSHER_FORCE_TLS | camunda.modeler.pusher.client.force-tls | no | false |
Feature flags
If you've set any of the following feature flags in the webapp configuration, add them to the restapi configuration instead.
Refer to the configuration page for details on these properties.
| Environment variable | Application property | Required? | Default value |
|---|---|---|---|
MARKETPLACE_ENABLED | camunda.marketplace.enabled | no | true |
FEATURE_AI_ENABLED | camunda.modeler.feature.ai-enabled | no | true |
ZEEBE_BPMN_DEPLOYMENT_ENABLED | camunda.modeler.feature.bpmn-deployment-enabled | no | true |
ZEEBE_DMN_DEPLOYMENT_ENABLED | camunda.modeler.feature.dmn-deployment-enabled | no | true |
PLAY_ENABLED | camunda.modeler.feature.play-enabled | no | true |
Resource import
If you've enabled the resource import from private IP addresses in the webapp configuration, enable it in the restapi configuration instead.
Refer to the configuration page for details on this property.
The name of the environment variable has changed from IMPORT_RESOURCES_ALLOW_PRIVATE_IP_ADDRESS (version 8.8 / webapp) to CAMUNDA_MODELER_RESOURCE_IMPORT_ALLOW_PRIVATE_IP_ADDRESS (version 8.9 / restapi).
| Environment variable | Application property | Required? | Default value |
|---|---|---|---|
CAMUNDA_MODELER_RESOURCE_IMPORT_ALLOW_PRIVATE_IP_ADDRESS | camunda.modeler.resource-import.allow-private-ip-address | no | false |
Logging
If you've changed the client log level for the webapp, configure it for the restapi instead.
Refer to the logging documentation for more details.
| Environment variable | Application property | Required? | Default value |
|---|---|---|---|
LOG_LEVEL_CLIENT | camunda.modeler.client.logging.level | no | WARN |
Proxy server
If you've configured an HTTP proxy server for the webapp, configure it for the restapi instead as described in the
proxy configuration troubleshooting guide.
SSL/TLS certificates
If you've provided custom (self-signed) SSL certificates for the webapp, configure them for the restapi instead as described in the
SSL configuration guide.
Logging framework
Web Modeler restapi now uses Apache Log4j 2 instead of Logback.
If you use a custom Logback configuration, migrate it to Log4j 2. See the Log4j migration guide for details.
Default logging configuration
The default logging configuration is included here for reference.
The default layout displays:
- time (hours, minutes, seconds, milliseconds)
- thread name
- MDC context (if present)
- log level
- logger name
- message
Example pattern
%d{HH:mm:ss.SSS} [%t] %notEmpty{[%X] }%-5level %logger{36} - %msg%n
For advanced configuration options, see logging.
Embedded web server
Web Modeler now uses Apache Tomcat as the embedded web server instead of Undertow.
If you use a custom Undertow configuration, review and migrate it.
Refer to:
Remove or replace Undertow properties
If your configuration includes:
server.undertow.*
These properties no longer apply when you switch to Tomcat, and must be removed or replaced.
Access log properties
| Undertow property | Replacement or action |
|---|---|
server.undertow.accesslog.enabled | Replace with server.tomcat.accesslog.enabled |
server.undertow.accesslog.pattern | Replace with server.tomcat.accesslog.pattern |
server.undertow.accesslog.dir | Replace with server.tomcat.basedir or a custom log directory |
server.undertow.accesslog.prefix | Tomcat uses server.tomcat.accesslog.prefix |
server.undertow.accesslog.rotate | Review rotation behavior; Tomcat rotates differently |
Threading properties
| Undertow property | Tomcat equivalent or action |
|---|---|
server.undertow.threads.io | Use server.tomcat.max-connections or a connector customizer |
server.undertow.threads.worker | Replace with server.tomcat.max-threads |
server.undertow.buffer-size | No direct equivalent; Tomcat uses internal buffer sizes |
server.undertow.direct-buffers | No direct equivalent; Tomcat uses NIO buffers differently |
Builder and handler customizations
The following properties do not have direct Tomcat equivalents and must be implemented programmatically or removed if not required:
server.undertow.eager-filter-init
server.undertow.allow-encoded-slash
server.undertow.decode-url
server.undertow.max-http-post-size
server.undertow.no-request-timeout
Implement customizations using:
TomcatServletWebServerFactoryTomcatConnectorCustomizer
More information on handling large payloads can be found here.
Review Tomcat properties
If you already define:
server.tomcat.*
Review these settings for correctness.
Access logs
| Tomcat property | Description |
|---|---|
server.tomcat.accesslog.enabled | Enable Tomcat access logs |
server.tomcat.accesslog.directory | Log directory |
server.tomcat.accesslog.pattern | Log format |
server.tomcat.accesslog.prefix | File name prefix |
server.tomcat.accesslog.suffix | File name suffix |
Tomcat rotates differently than Undertow. Verify log retention and file sizes.
Performance and threading
| Property | Description |
|---|---|
server.tomcat.max-connections | Maximum concurrent connections |
server.tomcat.accept-count | Queue size for incoming connections |
server.tomcat.max-threads | Maximum request-processing threads |
server.tomcat.min-spare-threads | Minimum idle threads |
Tomcat uses a standard blocking I/O thread model, unlike Undertow’s worker and IO threads.
MBean registry
Tomcat disables the MBean registry by default:
Enable it if you require Java Management Extensions (JMX) metrics:
server.tomcat.mbeanregistry.enabled: true
Additional Tomcat settings
| Property | Notes |
|---|---|
server.tomcat.connection-timeout | Review default values; they differ from Undertow |
Review behavioral differences
When migrating configuration, also review behavioral differences between Undertow and Tomcat.
Large payload handling
Undertow used server.undertow.max-http-post-size.
Tomcat uses:
spring.servlet.multipart.max-file-size
spring.servlet.multipart.max-request-size
server.tomcat.max-swallow-size
Review these settings if your deployment handles large uploads.