Configure Helm chart components

This page explains how to configure Camunda components in Helm charts. You can define options in values.yaml and provide custom files for additional configuration.

Prerequisites

• A deployed Camunda Helm chart release.
• Access to the values.yaml file.
• Basic understanding of Spring Boot configuration (application.yaml or application.properties).

Configuration

Parameters

Key	Type	Description
<componentName>.configuration	string	Full application configuration content (for example, the contents of application.yaml).
<componentName>.extraConfiguration	map	Additional configuration files. Keys are filenames, values are file contents. Mounted into the container at ./config.

Configuration options

Two Helm values are available for component configuration:

• <componentName>.configuration
• <componentName>.extraConfiguration

note

In Camunda 8.8, Zeebe, Operate, and Tasklist are merged into the Orchestration Cluster. The Helm key for all three components is orchestration, replacing the former zeebe, operate, and tasklist keys.

componentName.configuration

Use <componentName>.configuration to define an application configuration file directly in values.yaml.

For example, to configure the Orchestration Cluster's Elasticsearch connection:

orchestration:
  configuration: |-
    camunda.operate:
      # ELS instance to store Operate data
      elasticsearch:
        # Cluster name
        clusterName: elasticsearch
        # Host
        host: <your-release-name>-elasticsearch
        # Transport port
        port: 9200
        numberOfShards: 3
      # ELS instance to export Zeebe data to
      zeebeElasticsearch:
        # Cluster name
        clusterName: elasticsearch
        # Host
        host: <your-release-name>-elasticsearch
        # Transport port
        port: 9200
        # Index prefix, configured in Zeebe Elasticsearch exporter
        prefix: zeebe-record
    #Spring Boot Actuator endpoints to be exposed
    management.endpoints.web.exposure.include: health,info,conditions,configprops,prometheus,loggers,usage-metrics,backups

componentName.extraConfiguration

Use <componentName>.extraConfiguration to provide additional configuration files. Each key is the filename, and each value is the file content. A common use case is providing a custom log4j2.xml file. When the Helm chart processes this option, it mounts the file under the ./config directory:

orchestration:
  extraConfiguration:
    log4j2.xml: |-
      <?xml version="1.0" encoding="UTF-8"?>
      <Configuration status="WARN" monitorInterval="30">
        <Properties>
          <Property name="LOG_PATTERN">%clr{%d{yyyy-MM-dd HH:mm:ss.SSS}}{faint} %clr{%5p} %clr{${sys:PID}}{magenta} %clr{---}{faint} %clr{[%15.15t]}{faint} %clr{%-40.40c{1.}}{cyan} %clr{:}{faint} %m%n%xwEx</Property>
          <Property name="log.stackdriver.serviceName">${env:ZEEBE_LOG_STACKDRIVER_SERVICENAME:-orchestration}</Property>
          <Property name="log.stackdriver.serviceVersion">${env:ZEEBE_LOG_STACKDRIVER_SERVICEVERSION:-}</Property>
        </Properties>
        <Appenders>
          <Console name="Console" target="SYSTEM_OUT" follow="true">
            <PatternLayout pattern="${LOG_PATTERN}"/>
          </Console>
          <Console name="Stackdriver" target="SYSTEM_OUT" follow="true">
            <StackdriverLayout serviceName="${log.stackdriver.serviceName}"
              serviceVersion="${log.stackdriver.serviceVersion}" />
          </Console>
        </Appenders>
        <Loggers>
          <Logger name="io.camunda" level="debug" />
          <Root level="debug">
            <AppenderRef ref="${env:CAMUNDA_LOG_APPENDER:-Console}"/>
          </Root>
        </Loggers>
      </Configuration>

Default properties

The helm template command generates the application's default configuration. Keep the original values.yaml unchanged and maintain a separate file with your custom settings. For details, see Creating your own values files. To generate the default configuration, replace <your-release-name> with your release name and run:

helm template <your-release-name> \
    -f values.yaml \
    camunda/camunda-platform \
    --show-only templates/orchestration/configmap-unified.yaml

The --show-only flag prints the configmap. Copy the application.yml content and place it under the appropriate <component>.configuration key in values.yaml.

Practical example: migrating from environment variables to a configuration file

This example shows how to convert a Zeebe backup configuration from environment variables to the application.yaml file format.

Step 1: Review the existing environment variable configuration

To configure Zeebe backups, earlier charts required environment variables:

orchestration:
  env:
    - name: ZEEBE_BROKER_DATA_BACKUP_S3_BUCKETNAME
      value: zeebebackuptest
    - name: ZEEBE_BROKER_DATA_BACKUP_S3_REGION
      value: us-east-1
    - name: ZEEBE_BROKER_DATA_BACKUP_STORE
      value: S3
    - name: ZEEBE_BROKER_DATA_BACKUP_S3_ENDPOINT
      value: http://loki-minio.monitoring.svc.cluster.local:9000
    - name: ZEEBE_BROKER_DATA_BACKUP_S3_ACCESSKEY
      value: supersecretaccesskey
    - name: ZEEBE_BROKER_DATA_BACKUP_S3_SECRETKEY
      value: supersecretkey
    - name: ZEEBE_BROKER_DATA_BACKUP_S3_APICALLTIMEOUT
      value: PT180S
    - name: ZEEBE_BROKER_DATA_BACKUP_S3_BASEPATH
      value: zeebebackup

Step 2: Generate the default configuration file

Run the following command to render the default configuration file and fill in Helm values:

helm template \
    -f values.yaml \
    camunda/camunda-platform \
    --show-only templates/orchestration/configmap-unified.yaml

The output includes an application.yml section similar to:

zeebe:
  broker:
    exporters:
      elasticsearch:
        className: "io.camunda.zeebe.exporter.ElasticsearchExporter"
        args:
          url: "http://RELEASE-elasticsearch:9200"
          index:
            prefix: "zeebe-record"
    gateway:
      enable: true
      network:
        port: 26500
      security:
        enabled: false
        authentication:
          mode: none
    network:
      host: 0.0.0.0
      commandApi:
        port: 26501
      internalApi:
        port: 26502
      monitoringApi:
        port: "9600"
    cluster:
      clusterSize: "1"
      replicationFactor: "1"
      partitionsCount: "1"
      clusterName: RELEASE-zeebe
    threads:
      cpuThreadCount: "3"
      ioThreadCount: "3"

Step 3: Map environment variables to configuration properties

For each environment variable, find the corresponding property in the Zeebe configuration.

For example, the environment variable ZEEBE_BROKER_DATA_BACKUP_S3_BUCKETNAME maps to the property zeebe.broker.data.backup.s3.bucketName, documented under Zeebe S3 Backup.

Add the property to the configuration file. Add the data section under zeebe.broker:

zeebe:
  broker:
    data:
      backup:
        s3:
          bucketName: "zeebebackuptest"
    exporters:
      elasticsearch:
        className: "io.camunda.zeebe.exporter.ElasticsearchExporter"
        args:
          url: "http://RELEASE-elasticsearch:9200"
          index:
            prefix: "zeebe-record"
    gateway:
      enable: true
      network:
        port: 26500
      security:
        enabled: false
        authentication:
          mode: none
    network:
      host: 0.0.0.0
      commandApi:
        port: 26501
      internalApi:
        port: 26502
      monitoringApi:
        port: "9600"
    cluster:
      clusterSize: "1"
      replicationFactor: "1"
      partitionsCount: "1"
      clusterName: RELEASE-zeebe
    threads:
      cpuThreadCount: "3"
      ioThreadCount: "3"

Step 4: Repeat for all environment variables

Follow the same process for each environment variable. The resulting configuration looks like this:

zeebe:
  broker:
    data:
      backup:
        store: "S3"
        s3:
          bucketName: "zeebebackuptest"
          region: "us-east-1"
          endpoint: "http://loki-minio.monitoring.svc.cluster.local:9000"
          accessKey: "supersecretaccesskey"
          secretKey: "supersecretkey"
          apiCallTimeout: "PT180S"
          basePath: "zeebebackup"

    exporters:
      elasticsearch:
        className: "io.camunda.zeebe.exporter.ElasticsearchExporter"
        args:
          url: "http://RELEASE-elasticsearch:9200"
          index:
            prefix: "zeebe-record"
    gateway:
      enable: true
      network:
        port: 26500
      security:
        enabled: false
        authentication:
          mode: none
    network:
      host: 0.0.0.0
      commandApi:
        port: 26501
      internalApi:
        port: 26502
      monitoringApi:
        port: "9600"
    cluster:
      clusterSize: "1"
      replicationFactor: "1"
      partitionsCount: "1"
      clusterName: RELEASE-zeebe
    threads:
      cpuThreadCount: "3"
      ioThreadCount: "3"

Step 5: Add the configuration to values.yaml

Finally, place the updated configuration under orchestration.configuration in values.yaml:

orchestration:
  configuration: |-
    zeebe:
      broker:
        data:
          backup:
            store: "S3"
            s3:
              bucketName: "zeebebackuptest"
              region: "us-east-1"
              endpoint: "http://loki-minio.monitoring.svc.cluster.local:9000"
              accessKey: "supersecretaccesskey"
              secretKey: "supersecretkey"
              apiCallTimeout: "PT180S"
              basePath: "zeebebackup"

        exporters:
          elasticsearch:
            className: "io.camunda.zeebe.exporter.ElasticsearchExporter"
            args:
              url: "http://RELEASE-elasticsearch:9200"
              index:
                prefix: "zeebe-record"
        gateway:
          enable: true
          network:
            port: 26500
          security:
            enabled: false
            authentication:
              mode: none
        network:
          host: 0.0.0.0
          commandApi:
            port: 26501
          internalApi:
            port: 26502
          monitoringApi:
            port: "9600"
        cluster:
          clusterSize: "1"
          replicationFactor: "1"
          partitionsCount: "1"
          clusterName: RELEASE-zeebe
        threads:
          cpuThreadCount: "3"
          ioThreadCount: "3"

Connectors configuration

info

Connectors are enabled by default in Camunda 8.8. This section covers configuration options for Connectors, including how to disable them if needed.

The Connector runtime is enabled by default. To use connectors, install connector element templates. For details, see Manage connector templates in Web Modeler or Configuring templates in Desktop Modeler.

For the full list of options, see the Connectors Helm values.

Disable Connectors

To disable Connectors, set connectors.enabled: false when deploying the Helm chart:

connectors:
  enabled: false

Polling authentication mode

Connectors use the Operate API to fetch process definitions that contain inbound connectors. Depending on your Camunda architecture, choose one of the following values for the inbound.mode parameter:

• disabled — Polling from Operate is disabled. The connector runtime supports only outbound interactions, such as HTTP REST calls.
• credentials — The connector runtime authenticates to the Operate API with basic HTTP authentication.
• oauth — (Recommended, and enabled by default) The connector runtime authenticates to the Operate API with OAuth 2.0. Camunda uses Keycloak as the default OAuth provider.

Troubleshooting

Conflicting options

If both an environment variable and a configuration file define the same option, the environment variable takes precedence.

Example:

orchestration:
  env:
    - name: ZEEBE_BROKER_DATA_BACKUP_S3_BUCKETNAME
      value: "zeebetest1"

  configuration: |
    zeebe:
      broker:
        data:
          backup:
            s3:
              bucketName: "zeebeOtherBucketName"
      ...

Here, the bucket name is set twice. The environment variable zeebetest1 overrides zeebeOtherBucketName from the configuration file. See Spring externalized configuration for precedence details.

Limitations

configuration is written as a full file replacement. It is not merged with defaults from the chart or container image.

• During upgrades, the component may fail to start until your custom file matches any new required schema.
• Multiline values must use a YAML block scalar (| or |-) to avoid Helm/YAML parse issues.
• If the same setting is defined in both env and configuration, env takes precedence at runtime.

Component-specific notes

Some components deviate from the standard application.yaml/log4j2.xml behavior.

Optimize

Optimize does not use Spring Boot's application.yaml. It reads environment-config.yaml. Setting optimize.configuration writes the provided content to environment-config.yaml inside the container.

optimize:
  configuration: |-
    # Contents go into environment-config.yaml, not application.yaml
    container:
      host: 0.0.0.0
      ports:
        http: 8090
    es:
      connection:
        nodes:
          - host: <your-release-name>-elasticsearch
            httpPort: 9200

For optimize.extraConfiguration, a common use case is a custom environment-logback.xml (not log4j2.xml):

optimize:
  extraConfiguration:
    environment-logback.xml: |-
      <configuration>
        ...
      </configuration>

For the full list of Optimize configuration options, see Optimize system configuration.

Console

Console does not support extraConfiguration. Use console.overrideConfiguration, which merges into the generated Console configuration (or into configuration supplied via console.configuration). Use it for Console-specific properties such as customerId, cluster tags, and custom-properties:

console:
  overrideConfiguration: |-
    customerId: "<your-customer-id>"
    clusters:
      - uuid: "<cluster-uuid>"
        name: "<cluster-name>"
        tags:
          - "<tag>"

For the full list of Console configuration options, see Console configuration.

References

For more details on where to find configuration options for specific components, see the following pages:

• Zeebe Broker
• Zeebe Gateway
• Operate
• Tasklist
• Web Modeler
• Console
• Connectors
• Identity
• Optimize