Skip to main content
Version: 8.9 (unreleased)

Configure Elasticsearch and OpenSearch index prefixes

Camunda components store operational data in Elasticsearch or OpenSearch indices. By default, Camunda uses the standard index names created by each exporter.

Configure an index prefix when you need to:

  • Organize indices by grouping related indices under a consistent naming pattern.
  • Isolate data when multiple Camunda instances share the same Elasticsearch or OpenSearch cluster, so they don’t write to or read from each other’s indices.
  • Avoid index name collisions in multi-instance environments (for example, separate dev/test/prod installations using one shared cluster).

Index prefix configuration​

When Elasticsearch/OpenSearch Exporter indices and Orchestration Cluster indices (secondary storage) share the same cluster, their prefixes must follow all of the rules below.

Requirements​

  1. Use unique prefixes – Do not reuse the same prefix for both index types.
  2. Avoid prefix relationships between prefixes – Neither prefix may match the other prefix’s wildcard pattern. In other words, the literal string of prefix A must not match prefixB*, and the literal string of prefix B must not match prefixA*. For example, custom (Elasticsearch/OpenSearch exporter) and custom-zeebe (Orchestration Cluster) are unsafe because custom* matches both groups, while custom-index1 and custom-index2 are safe because custom-index1* matches only custom-index1… indices and custom-index2* matches only custom-index2… indices.
  3. Avoid reserved names as bare prefixes – Do not use operate, tasklist, or camunda as the full exporter prefix. Using these names as part of a longer custom prefix (for example, custom-camunda) is allowed, as long as rules 1 and 2 are still satisfied.

Configuration properties​

Index typeConfiguration property
Elasticsearch/OpenSearch Exporter indiceszeebe.broker.exporters.{elasticsearch|opensearch}.args.index.prefix (and ZEEBE_BROKER_EXPORTERS_{ELASTICSEARCH|OPENSEARCH}_ARGS_INDEX_PREFIX)
Orchestration Cluster indicescamunda.data.secondary-storage.{elasticsearch|opensearch}.index-prefix (and CAMUNDA_DATA_SECONDARYSTORAGE_{ELASTICSEARCH|OPENSEARCH}_INDEXPREFIX)

Common mistakes to avoid​

  • Do not set the Orchestration Cluster index prefix to zeebe-record (the default exporter prefix zeebe.broker.exporters.{elasticsearch|opensearch}.args.index.prefix).
  • Do not set the exporter prefix to operate, tasklist, or camunda.

Why this matters​

Prefixes that violate these rules can cause ILM/ISM policies and wildcard patterns to match unintended indices, potentially leading to unexpected data loss.

warning

Changing an index prefix after a Camunda instance has been running creates new, empty indices with the new prefix. Camunda does not provide built‑in migration support between old and new prefixes.

Exporters and index prefixes​

Starting with Camunda 8.8, index prefixes are configured per exporter. Camunda uses two exporters, and each exporter has its own index prefix configuration.

Camunda Exporter (default)​

The Camunda Exporter is enabled by default. It creates Orchestration Cluster indices used by the Orchestration Cluster (Operate and Tasklist).

  • Helm configuration: orchestration.index.prefix
  • Default value: "" (empty string, meaning no prefix)
  • Controlled by: orchestration.exporters.camunda.enabled: true (default)

Legacy Zeebe Exporter​

The Legacy Zeebe Exporter creates zeebe-record indices. This exporter is disabled by default. Optimize reads from the zeebe-record indices. When Optimize is enabled, the Legacy Zeebe Exporter is automatically enabled to provide these indices.

  • Helm configuration: global.elasticsearch.prefix or global.opensearch.prefix
  • Default value: zeebe-record
  • Controlled by: orchestration.exporters.zeebe.enabled: false (default)
When the Legacy Zeebe Exporter is used

The legacy Zeebe Exporter is automatically enabled when:

  • Optimize is enabled (optimize.enabled: true)
  • You explicitly enable it (orchestration.exporters.zeebe.enabled: true)
  • Data migration from pre-8.8 versions is required

Configuration reference​

ConfigurationDefaultUsed ByPurpose
orchestration.index.prefix""Camunda Exporter, Orchestration ClusterPrefix for Orchestration Cluster indices
global.elasticsearch.prefixzeebe-recordLegacy Zeebe ExporterPrefix for zeebe-record indices (consumed by Optimize)
global.opensearch.prefixzeebe-recordLegacy Zeebe ExporterPrefix for zeebe-record indices when using OpenSearch

Optimize-specific configuration​

When you use a custom prefix for zeebe-record indices and Optimize is enabled, you must also configure Optimize to use the same prefixes. If these values do not match the exporter prefix exactly, Optimize can start but does not display process data.

Environment VariablePurpose
CAMUNDA_OPTIMIZE_ELASTICSEARCH_SETTINGS_INDEX_PREFIXPrefix for Optimize's own indices (Elasticsearch)
CAMUNDA_OPTIMIZE_OPENSEARCH_SETTINGS_INDEX_PREFIXPrefix for Optimize's own indices (OpenSearch)
CAMUNDA_OPTIMIZE_ZEEBE_NAMEMust match global.elasticsearch.prefix or global.opensearch.prefix

Configure index prefixes​

Basic configuration (without Optimize)​

If Optimize is not enabled, configure only the Camunda Exporter prefix.

orchestration:
  index:
    prefix: custom-camunda # Orchestration Cluster indices prefix

Full configuration (with Optimize)​

When Optimize is enabled, configure:

  • The Legacy Zeebe Exporter prefix (global.elasticsearch.prefix or global.opensearch.prefix)
  • The Camunda Exporter prefix (orchestration.index.prefix)
  • Optimize environment variables so Optimize can find the correct indices
global:
  elasticsearch:
    enabled: true
    prefix: custom-zeebe # Legacy Zeebe Exporter prefix (read by Optimize)

orchestration:
  index:
    prefix: custom-camunda # Camunda Exporter prefix

optimize:
  enabled: true
  env:
    - name: CAMUNDA_OPTIMIZE_ELASTICSEARCH_SETTINGS_INDEX_PREFIX
      value: custom-optimize # Optimize's own indices
    - name: CAMUNDA_OPTIMIZE_ZEEBE_NAME
      value: custom-zeebe # Must match global.elasticsearch.prefix

References​