Add custom configuration files with ConfigMaps or Secrets

On Elastic Cloud on Kubernetes, custom configuration files such as synonym dictionaries, SAML metadata, or CA certificates are stored in a ConfigMap or Secret, then mounted into your Elasticsearch pods with volumes and volume mounts.

This page walks through a synonyms file for the synonym token filter. You can use the same pattern for any other file you want to mount into the configuration directory of Elasticsearch, like adding CA certificates of external systems for example.

There are multiple ways to create and mount ConfigMaps and Secrets on Kubernetes. Refer to the Kubernetes documentation for details.

This example creates a ConfigMap named synonyms from a local file my-synonyms.txt, stored under the key synonyms-elasticsearch.txt:

kubectl create configmap synonyms -n <namespace> --from-file=synonyms-elasticsearch.txt=my-synonyms.txt
		

Update your Elasticsearch manifest to mount the synonyms ConfigMap at /usr/share/elasticsearch/config/dictionaries:

spec:
  nodeSets:
  - name: default
    count: 3
    podTemplate:
      spec:
        containers:
        - name: elasticsearch
          volumeMounts:
          - name: synonyms
            mountPath: /usr/share/elasticsearch/config/dictionaries
        volumes:
        - name: synonyms
          configMap:
            name: synonyms
		

1. Elasticsearch runs by convention in a container called elasticsearch. Do not change that value.
2. Always use a path under /usr/share/elasticsearch/config.
3. Use secret instead of configMap if you stored the data in a Secret.
4. The ConfigMap name must match the ConfigMap created in the previous step.

After you apply the changes, the nodes can read dictionaries/synonyms-elasticsearch.txt and reference it from any configuration setting.