Use external Elasticsearch with Helm

Configure Camunda 8 Self-Managed to connect to an external Elasticsearch instance as a secondary storage backend. Elasticsearch is used for indexing and querying operational data consumed by multiple Camunda components. For a canonical definition, see Elasticsearch/OpenSearch.

By default, the Helm chart deployment provisions an Elasticsearch instance using the bundled Elasticsearch subchart. You can instead connect Camunda to an existing external Elasticsearch instance, either running inside the same Kubernetes cluster or outside it.

Secondary storage is configurable. For supported components, you can use an RDBMS-based secondary store instead. See RDBMS configuration and the glossary entry RDBMS for configuration details and limitations.

For production deployments, Camunda recommends managing Elasticsearch externally and disabling the Elasticsearch subchart. This gives more flexibility for scaling, backups, and upgrades without affecting the rest of the Camunda installation.

note

In 8.9-alpha3, H2 is the default secondary storage for lightweight Camunda 8 Run and quick-install scenarios. Elasticsearch is still bundled with the distribution and fully supported as an optional alternative. Use this guide when you want to run or connect to an external Elasticsearch cluster instead of the default H2 store.

Prerequisites

Before configuring, collect the following information about your external Elasticsearch instance:

• URL to access the cluster (protocol, host, and port)
• Authentication requirements and credentials (if needed)
• TLS requirements:
  • Whether the certificate is publicly trusted
  • Whether you need to provide a custom or self-signed certificate

Configuration

Parameters

values.yaml option	type	default	description
global.elasticsearch.enabled	boolean	false	Enable or disable all components connecting to Elasticsearch.
global.elasticsearch.external.true	boolean	false	Set to true to connect to an external Elasticsearch instance.
global.elasticsearch.auth.username	string	""	HTTP Basic username for Elasticsearch authentication.
global.elasticsearch.auth.password	string	""	HTTP Basic password for Elasticsearch authentication.
global.elasticsearch.prefix	string	zeebe-record	Index prefix for zeebe-record indices. See Configure Elasticsearch and OpenSearch index prefixes.
global.elasticsearch.tls.enabled	boolean	false	Enables TLS when connecting to Elasticsearch.
global.elasticsearch.tls.secret.inlineSecret	string	""	TLS certificate specified directly in values.yaml.
global.elasticsearch.tls.secret.existingSecret	string	""	Kubernetes Secret name containing a TLS certificate.
global.elasticsearch.tls.secret.existingSecretKey	string	""	Kubernetes Secret key with the TLS certificate.
global.elasticsearch.url.protocol	string	http	Protocol to use when connecting to Elasticsearch. Possible values are http and https.
global.elasticsearch.url.host	string	{{ .Release.Name }}-elasticsearch	Hostname or IP address of the Elasticsearch instance.
global.elasticsearch.url.port	integer	9200	Port number of the Elasticsearch instance.
elasticsearch.enabled	boolean	false	Enables or disables the bundled Elasticsearch subchart.

Example usage

Connect to external Elasticsearch without a certificate

By default, global.elasticsearch.url.protocol is set to http. This makes it possible to connect to Elasticsearch without TLS.

Configure the Camunda 8 Self-Managed Helm chart as follows:

global:
  elasticsearch:
    enabled: true
    external: true
    auth:
      username: elastic
      secret:
        inlineSecret: pass
    url:
      protocol: http
      host: elastic.example.com
      port: 443

elasticsearch:
  enabled: false

Connect to external Elasticsearch with a self-signed certificate

If the Elasticsearch cluster accepts only https requests with a self-signed certificate:

1. Create an externaldb.jks file from the Elasticsearch certificate file. For example, using the keytool CLI:

   keytool -import -alias elasticsearch -keystore externaldb.jks -storetype jks -file elastic.crt -storepass changeit -noprompt

2. Create a Kubernetes secret from the externaldb.jks file before installing Camunda:

   kubectl  create secret -n camunda generic elastic-jks --from-file=externaldb.jks

3. Configure the Camunda 8 Self-Managed Helm chart:

   global:
     elasticsearch:
       enabled: true
       external: true
       tls:
         enabled: true
         existingSecret: elastic-jks
       auth:
         username: elastic
         secret:
           inlineSecret: pass
       url:
         protocol: https
         host: elastic.example.com
         port: 443
   
   elasticsearch:
     enabled: false

Connect to external Elasticsearch with a publicly trusted certificate

This configuration works with managed Elasticsearch services. It has been tested with Elastic Cloud on Google Cloud.

global:
  elasticsearch:
    enabled: true
    external: true
    auth:
      username: elastic
      secret:
        inlineSecret: pass
    url:
      protocol: https
      host: elastic.example.com
      port: 443

elasticsearch:
  enabled: false

Connect to external Elasticsearch with custom index prefixes

When running multiple Camunda instances on a shared Elasticsearch cluster, use custom index prefixes to isolate data:

global:
  elasticsearch:
    enabled: true
    external: true
    prefix: my-env-zeebe # Prefix for zeebe-record indices
    auth:
      username: elastic
      secret:
        inlineSecret: pass
    url:
      protocol: https
      host: elastic.example.com
      port: 443

orchestration:
  index:
    prefix: my-env-camunda # Prefix for Orchestration Cluster indices

elasticsearch:
  enabled: false

For more details on index prefix configuration, including Optimize-specific settings, see Prefix Elasticsearch/OpenSearch indices.

Troubleshooting

If Zeebe pods fail, check for the following error:

• The host is unreachable or DNS is not properly resolving to an IP address listening on the specified port.

  Caused by: java.net.UnknownHostException: elastic.example.com

References

• Camunda production installation guide with Kubernetes and Helm (8.8 version not yet available)
• Configure Elasticsearch and OpenSearch index prefixes

Next steps

Use the custom values file to deploy Camunda 8:

helm install camunda camunda/camunda-platform --version $HELM_CHART_VERSION -f existing-elasticsearch-values.yaml