For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (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.

This page applies to both the Orchestration Cluster and Optimize when they use Elasticsearch or OpenSearch in Helm deployments.

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 Orchestration Cluster applications and APIs, including 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 consumed by Optimize. In the Camunda 8.10 Helm chart, the exporter requires Optimize and its Elasticsearch or OpenSearch backend to be enabled.

  • Helm configuration: optimize.database.elasticsearch.prefix or optimize.database.opensearch.prefix
  • Default value: zeebe-record
  • Required consumer: Optimize (optimize.enabled: true)
When the legacy Zeebe Exporter is used

In single-region deployments, the chart automatically enables the legacy Zeebe Exporter when Optimize and its Elasticsearch or OpenSearch backend are enabled. Setting orchestration.exporters.zeebe.enabled: true does not enable the exporter without Optimize.

When Optimize is disabled, optimize.database.elasticsearch.prefix and optimize.database.opensearch.prefix have no effect. You can still configure the Camunda Exporter prefix with orchestration.index.prefix.

Configuration reference​

ConfigurationDefaultUsed ByPurpose
orchestration.index.prefix""Camunda Exporter, Orchestration ClusterPrefix for Orchestration Cluster indices
optimize.database.elasticsearch.prefixzeebe-recordLegacy Zeebe ExporterPrefix for zeebe-record indices (consumed by Optimize)
optimize.database.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 optimize.database.elasticsearch.prefix or optimize.database.opensearch.prefix

Configure index prefixes​

Basic configuration (without Optimize)​

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

orchestration:
  data:
    secondaryStorage:
      type: elasticsearch
  index:
    prefix: custom-camunda # Orchestration Cluster indices prefix

Full configuration (with Optimize)​

When Optimize is enabled, configure:

  • The Legacy Zeebe Exporter prefix (optimize.database.elasticsearch.prefix or optimize.database.opensearch.prefix)
  • The Camunda Exporter prefix (orchestration.index.prefix)
  • Optimize environment variables so Optimize can find the correct indices
orchestration:
  data:
    secondaryStorage:
      type: elasticsearch
  index:
    prefix: custom-camunda # Camunda Exporter prefix

optimize:
  enabled: true
  database:
    elasticsearch:
      enabled: true
      prefix: custom-zeebe # Legacy Zeebe Exporter prefix (read by Optimize)
  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 optimize.database.elasticsearch.prefix

References​