plugins and config files updated

Author: eedugon

deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md

@@ -7,7 +7,7 @@ mapped_pages:
 
 # Custom configuration files and plugins [k8s-bundles-plugins]
 
-To run Elasticsearch with specific plugins or configuration files installed on ECK, you have two options. Each option has its own pros and cons.
+To run Elasticsearch with specific plugins or configuration files installed on ECK, you have multiple options. Each option has its own pros and cons.
 
 1. Create a custom container image with the required plugins and configuration files.
 
@@ -35,9 +35,26 @@ To run Elasticsearch with specific plugins or configuration files installed on E
         * Each Elasticsearch node needs to repeat the download, wasting bandwidth and slowing startup.
         * Deployment manifests are more complicated.
 
+3. Use ConfigMaps or Secrets together with volumes and volume mounts for configuration files.
+
+    * **Pros**
+
+        * Best choice for injecting configuration files into your {{es}} nodes.
+        * Follows standard Kubernetes methodology to mount files into Pods.
+
+    * **Cons**
+
+        * Not valid for plugins installation.
+        * Requires to maintain the ConfigMaps or Secrets with the content of the files.
+
+The following sections provide examples for each of the mentioned options.
+
+## Create a custom image
 
 Refer to [Creating custom images](create-custom-images.md) for instructions on how to build custom Docker images based on the official Elastic images.
 
+## Use init containers for plugins installation
+
 The following example describes option 2, using a repository plugin. To install the plugin before the Elasticsearch nodes start, use an init container to run the [plugin installation tool](https://www.elastic.co/guide/en/elasticsearch/plugins/current/installation.html).
 
 ```yaml
@@ -57,9 +74,9 @@ spec:
             bin/elasticsearch-plugin install --batch repository-azure
 ```
 
-To install custom configuration files you can use volumes and volume mounts.
+### Note when using Istio [istio-note]
 
-The next example shows how to add a synonyms file for the [synonym token filter](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-synonym-tokenfilter.html) in Elasticsearch. But you can use the same approach for any kind of file you want to mount into the configuration directory of Elasticsearch.
+When using Istio, init containers do **not** have network access, as the Envoy sidecar that provides network connectivity is not started yet. In this scenario, custom containers are the best option. If custom containers are simply not a viable option, then it is possible to adjust the startup command for the elasticsearch container itself to run the plugin installation before starting Elasticsearch, as the following example describes. Note that this approach will require updating the startup command if it changes in the Elasticsearch image, which could potentially cause failures during upgrades.
 
 ```yaml
 spec:
@@ -69,24 +86,45 @@ spec:
     podTemplate:
       spec:
         containers:
-        - name: elasticsearch <1>
-          volumeMounts:
-          - name: synonyms
-            mountPath: /usr/share/elasticsearch/config/dictionaries
-        volumes:
-        - name: synonyms
-          configMap:
-            name: synonyms <2>
+        - name: elasticsearch
+          command:
+          - /usr/bin/env
+          - bash
+          - -c
+          - |
+            #!/usr/bin/env bash
+            set -e
+            bin/elasticsearch-plugin remove --purge repository-s3 || true
+            bin/elasticsearch-plugin install --batch repository-s3
+            /bin/tini -- /usr/local/bin/docker-entrypoint.sh
 ```
 
-1. Elasticsearch runs by convention in a container called *elasticsearch*.
-2. Assuming you have created a config map in the same namespace as Elasticsearch with the name *synonyms* containing the synonyms file(s).
+## Use a volume and volume mount together with a ConfigMap or Secret
 
+To install custom configuration files you can:
 
-$$$istio-note$$$
-**Note when using Istio**
+1. Add the configuration data into a ConfigMap or Secret.
+2. Use volumes and volume mounts in your manifest to mount the contents of the ConfigMap or Secret as files in your {{es}} nodes.
 
-When using Istio, init containers do **not** have network access, as the Envoy sidecar that provides network connectivity is not started yet. In this scenario, custom containers are the best option. If custom containers are simply not a viable option, then it is possible to adjust the startup command for the elasticsearch container itself to run the plugin installation before starting Elasticsearch, as the following example describes. Note that this approach will require updating the startup command if it changes in the Elasticsearch image, which could potentially cause failures during upgrades.
+The next example shows how to add a synonyms file for the [synonym token filter](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-synonym-tokenfilter.html) in Elasticsearch. But you can **use the same approach for any kind of file you want to mount into the configuration directory of Elasticsearch**, like adding CA certificates of external systems.
+
+1. Create the ConfigMap or Secret with the data:
+
+There are multiple ways to create and mount [ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/) and [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) on Kubernetes. Refer to the official documentation for more details.
+
+This example shows how to create a ConfigMap named `synonyms` with the content of a local file named `my-synonyms.txt` added into the `synonyms-elasticsearch.txt` key of the ConfigMap.
+
+```sh
+kubectl create configmap synonyms -n <namespace> --from-file=my-synonyms.txt=synonyms-elasticsearch.txt
+```
+
+::::{tip}
+Create the ConfigMap or Secret in the same namespace where your {{es}} cluster runs.
+::::
+
+2. Declare the ConfigMap as a volume and mount it in the Elasticsearch containers.
+
+In this example, modify your {{es}} manifest to mount the contents of the `synonyms` ConfigMap into `/usr/share/elasticsearch/config/dictionaries` on the {{es}} nodes.
 
 ```yaml
 spec:
@@ -96,15 +134,19 @@ spec:
     podTemplate:
       spec:
         containers:
-        - name: elasticsearch
-          command:
-          - /usr/bin/env
-          - bash
-          - -c
-          - |
-            #!/usr/bin/env bash
-            set -e
-            bin/elasticsearch-plugin remove --purge repository-s3 || true
-            bin/elasticsearch-plugin install --batch repository-s3
-            /bin/tini -- /usr/local/bin/docker-entrypoint.sh
+        - name: elasticsearch <1>
+          volumeMounts:
+          - name: synonyms
+            mountPath: /usr/share/elasticsearch/config/dictionaries <2>
+        volumes:
+        - name: synonyms
+          configMap: <3>
+            name: synonyms <4>
 ```
+
+1. Elasticsearch runs by convention in a container called `elasticsearch`. Do not change that value.
+2. Use always a path under `/usr/share/elasticsearch/config`.
+3. Use `secret` instead of `configMap` if you used a secret to store the data.
+4. The ConfigMap name must be the same as the ConfigMap created in the previous step.
+
+After the changes are applied, {{es}} nodes should be able to access `dictionaries/synonyms-elasticsearch.txt` and use it in any [configuration setting](./node-configuration.md).