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.
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:
Web Modeler
Cluster configuration
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.