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 type	Configuration property
Elasticsearch/OpenSearch Exporter indices	zeebe.broker.exporters.{elasticsearch|opensearch}.args.index.prefix (and ZEEBE_BROKER_EXPORTERS_{ELASTICSEARCH|OPENSEARCH}_ARGS_INDEX_PREFIX)
Orchestration Cluster indices	camunda.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. Optimize reads these indices. The Optimize instance can run in the same release or in a separate optimize release.

• Helm configuration: orchestration.exporters.zeebe.index.prefix. If this value is empty, the chart uses optimize.database.elasticsearch.prefix or optimize.database.opensearch.prefix.
• Default value: zeebe-record
• Enabled by: Optimize with an Elasticsearch or OpenSearch backend in the same release, or orchestration.exporters.zeebe.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 in the same release. Without Optimize in the release, set orchestration.exporters.zeebe.enabled: true to enable it against the Elasticsearch or OpenSearch secondary storage, and set its prefix with orchestration.exporters.zeebe.index.prefix. This is how a separate Optimize release gets its records. See export records for Optimize.

When Optimize is disabled, optimize.database.elasticsearch.prefix and optimize.database.opensearch.prefix don't configure Optimize. The legacy Zeebe Exporter still uses them as its prefix when orchestration.exporters.zeebe.index.prefix is empty, so check them before you rely on the default zeebe-record. You can still configure the Camunda Exporter prefix with orchestration.index.prefix.

Prefixes in the split topology

Each Orchestration Cluster and each Physical Tenant in the deployment topology needs its own index prefixes.

The Orchestration Cluster writes records and Optimize reads them. Optimize runs in the orchestration release or in a separate Optimize release per Physical Tenant. Authentication doesn't isolate shared Elasticsearch or OpenSearch storage. Prefixes keep the data of each cluster and tenant apart. To restrict who can read it, also use the access controls of your Elasticsearch or OpenSearch backend.

Prefix family	Configuration	Requirement
Orchestration application indices	Default: orchestration.index.prefix. Physical Tenant: camunda.physical-tenants.<id>.data.secondary-storage.<backend>.index-prefix	Unique per cluster and tenant
Legacy exporter writer	Default: orchestration.exporters.zeebe.index.prefix, or the exporter assigned to an explicit default entry. Physical Tenant: its exporter args.index.prefix	Unique per cluster and tenant
Optimize reader	optimize.database.elasticsearch.prefix or optimize.database.opensearch.prefix	Must exactly equal that tenant's Legacy exporter writer prefix
Optimize application indices	CAMUNDA_OPTIMIZE_ELASTICSEARCH_SETTINGS_INDEX_PREFIX or CAMUNDA_OPTIMIZE_OPENSEARCH_SETTINGS_INDEX_PREFIX in optimize.env	Unique per Optimize release, and different from every writer prefix

Every prefix in this table must also follow the requirements, across every cluster, tenant, and Optimize release that shares the storage. Being distinct isn't sufficient: alpha and alpha-tenant are distinct, but alpha* matches both. The only exception is each tenant's Optimize reader prefix, which must equal its writer prefix.

A wrong prefix doesn't cause an error:

• If you reuse a prefix, the records of one cluster or tenant show in the Operate, Tasklist, or Optimize data of another.
• If the writer and reader prefixes are different, Optimize starts against the wrong record set or an empty record set. Similar values aren't sufficient.

Configuration reference

Configuration	Default	Used By	Purpose
orchestration.index.prefix	""	Camunda Exporter, Orchestration Cluster	Prefix for Orchestration Cluster indices
orchestration.exporters.zeebe.index.prefix	""	Legacy Zeebe Exporter	Prefix for zeebe-record indices. When empty, falls back to optimize.database.elasticsearch.prefix or optimize.database.opensearch.prefix, then to zeebe-record
optimize.database.elasticsearch.prefix	zeebe-record	Optimize, and the Legacy Zeebe Exporter as a fallback	Optimize reader prefix for zeebe-record indices (Elasticsearch). The exporter uses it only when orchestration.exporters.zeebe.index.prefix is empty
optimize.database.opensearch.prefix	zeebe-record	Optimize, and the Legacy Zeebe Exporter as a fallback	Optimize reader prefix for zeebe-record indices (OpenSearch). The exporter uses it only when orchestration.exporters.zeebe.index.prefix is empty

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 Variable	Purpose
CAMUNDA_OPTIMIZE_ELASTICSEARCH_SETTINGS_INDEX_PREFIX	Prefix for Optimize's own indices (Elasticsearch)
CAMUNDA_OPTIMIZE_OPENSEARCH_SETTINGS_INDEX_PREFIX	Prefix for Optimize's own indices (OpenSearch)
CAMUNDA_OPTIMIZE_ZEEBE_NAME	Must match optimize.database.elasticsearch.prefix or optimize.database.opensearch.prefix

Configure index prefixes

values.yaml

Basic configuration (without Optimize)

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

Elasticsearch

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

OpenSearch

orchestration:
  data:
    secondaryStorage:
      type: opensearch
  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

Elasticsearch

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

OpenSearch

orchestration:
  data:
    secondaryStorage:
      type: opensearch
  index:
    prefix: custom-camunda # Camunda Exporter prefix

optimize:
  enabled: true
  database:
    opensearch:
      enabled: true
      prefix: custom-zeebe # Legacy Zeebe Exporter prefix (read by Optimize)
  env:
    - name: CAMUNDA_OPTIMIZE_OPENSEARCH_SETTINGS_INDEX_PREFIX
      value: custom-optimize # Optimize's own indices
    - name: CAMUNDA_OPTIMIZE_ZEEBE_NAME
      value: custom-zeebe # Must match optimize.database.opensearch.prefix
  migration:
    env:
      - name: CAMUNDA_OPTIMIZE_OPENSEARCH_SETTINGS_INDEX_PREFIX
        value: custom-optimize
      - name: CAMUNDA_OPTIMIZE_ZEEBE_NAME
        value: custom-zeebe

Environment variables

Elasticsearch

# Camunda Exporter - Orchestration Cluster indices prefix
CAMUNDA_DATA_SECONDARYSTORAGE_ELASTICSEARCH_INDEXPREFIX=custom-camunda

# Legacy Zeebe Exporter - zeebe-record indices prefix (for Optimize)
ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INDEX_PREFIX=custom-zeebe

# Optimize indices prefix (when Optimize is enabled)
CAMUNDA_OPTIMIZE_ELASTICSEARCH_SETTINGS_INDEX_PREFIX=custom-optimize
CAMUNDA_OPTIMIZE_ZEEBE_NAME=custom-zeebe

For example, recommended:

ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INDEX_PREFIX=custom-zeebe
CAMUNDA_DATA_SECONDARYSTORAGE_ELASTICSEARCH_INDEXPREFIX=custom-camunda

Not allowed (will cause conflicts):

ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INDEX_PREFIX=shared-prefix
CAMUNDA_DATA_SECONDARYSTORAGE_ELASTICSEARCH_INDEXPREFIX=shared-prefix

OpenSearch

# Camunda Exporter - Orchestration Cluster indices prefix
CAMUNDA_DATA_SECONDARYSTORAGE_OPENSEARCH_INDEXPREFIX=custom-camunda

# Legacy Zeebe Exporter - zeebe-record indices prefix (for Optimize)
ZEEBE_BROKER_EXPORTERS_OPENSEARCH_ARGS_INDEX_PREFIX=custom-zeebe

# Optimize indices prefix (when Optimize is enabled)
CAMUNDA_OPTIMIZE_OPENSEARCH_SETTINGS_INDEX_PREFIX=custom-optimize
CAMUNDA_OPTIMIZE_ZEEBE_NAME=custom-zeebe

For example, recommended:

ZEEBE_BROKER_EXPORTERS_OPENSEARCH_ARGS_INDEX_PREFIX=custom-zeebe
CAMUNDA_DATA_SECONDARYSTORAGE_OPENSEARCH_INDEXPREFIX=custom-camunda

Not allowed (will cause conflicts):

ZEEBE_BROKER_EXPORTERS_OPENSEARCH_ARGS_INDEX_PREFIX=shared-prefix
CAMUNDA_DATA_SECONDARYSTORAGE_OPENSEARCH_INDEXPREFIX=shared-prefix

application.yaml

Elasticsearch

camunda:
  data:
    secondary-storage:
      elasticsearch:
        index-prefix: custom-camunda # Camunda Exporter prefix

zeebe:
  broker:
    exporters:
      elasticsearch:
        args:
          index:
            prefix: custom-zeebe # Legacy Zeebe Exporter prefix

OpenSearch

camunda:
  data:
    secondary-storage:
      opensearch:
        index-prefix: custom-camunda # Camunda Exporter prefix

zeebe:
  broker:
    exporters:
      opensearch:
        args:
          index:
            prefix: custom-zeebe # Legacy Zeebe Exporter prefix

References

• Use external Elasticsearch
• Use external OpenSearch