Elasticsearch Helm Chart

This Helm chart is a lightweight way to configure and run our official Elasticsearch Docker image.

Warning: This branch is used for development, please use the latest 7.x release for released version.

• Requirements
• Installing
  • Install released version using Helm repository
  • Install development version using main branch
• Upgrading
• Usage notes
• Configuration
  • Deprecated
• FAQ
  • How to deploy this chart on a specific K8S distribution?
  • How to deploy dedicated nodes types?
    • Coordinating nodes
    • Clustering and Node Discovery
  • How to deploy clusters with security (authentication and TLS) enabled?
  • How to migrate from helm/charts stable chart?
  • How to install plugins?
  • How to use the keystore?
    • Basic example
    • Multiple keys
    • Custom paths and keys
  • How to enable snapshotting?
  • How to configure templates post-deployment?
• Contributing

Requirements

• Kubernetes >= 1.14
• Helm >= 2.17.0
• Minimum cluster requirements include the following to run this chart with default settings. All of these settings are configurable.
  • Three Kubernetes nodes to respect the default "hard" affinity settings
  • 1GB of RAM for the JVM heap

See supported configurations for more details.

Installing

Install released version using Helm repository

• Add the Elastic Helm charts repo: helm repo add elastic https://helm.elastic.co

• Install it:

  • with Helm 3: helm install elasticsearch elastic/elasticsearch
  • with Helm 2 (deprecated): helm install --name elasticsearch elastic/elasticsearch

Install development version using main branch

• Clone the git repo: git clone [email protected]:elastic/helm-charts.git

• Install it:

  • with Helm 3: helm install elasticsearch ./helm-charts/elasticsearch --set imageTag=8.1.0
  • with Helm 2 (deprecated): helm install --name elasticsearch ./helm-charts/elasticsearch --set imageTag=8.1.0

Upgrading

Please always check CHANGELOG.md and BREAKING_CHANGES.md before upgrading to a new chart version.

Usage notes

• This repo includes a number of examples configurations which can be used as a reference. They are also used in the automated testing of this chart.
• Automated testing of this chart is currently only run against GKE (Google Kubernetes Engine).
• The chart deploys a StatefulSet and by default will do an automated rolling update of your cluster. It does this by waiting for the cluster health to become green after each instance is updated. If you prefer to update manually you can set OnDelete updateStrategy.
• It is important to verify that the JVM heap size in esJavaOpts and to set the CPU/Memory resources to something suitable for your cluster.
• To simplify chart and maintenance each set of node groups is deployed as a separate Helm release. Take a look at the multi example to get an idea for how this works. Without doing this it isn't possible to resize persistent volumes in a StatefulSet. By setting it up this way it makes it possible to add more nodes with a new storage size then drain the old ones. It also solves the problem of allowing the user to determine which node groups to update first when doing upgrades or changes.
• We have designed this chart to be very un-opinionated about how to configure Elasticsearch. It exposes ways to set environment variables and mount secrets inside of the container. Doing this makes it much easier for this chart to support multiple versions with minimal changes.

Configuration

Deprecated

FAQ

How to deploy this chart on a specific K8S distribution?

This chart is designed to run on production scale Kubernetes clusters with multiple nodes, lots of memory and persistent storage. For that reason it can be a bit tricky to run them against local Kubernetes environments such as Minikube.

This chart is highly tested with GKE, but some K8S distribution also requires specific configurations.

We provide examples of configuration for the following K8S providers:

• Docker for Mac
• KIND
• Minikube
• MicroK8S
• OpenShift

How to deploy dedicated nodes types?

All the Elasticsearch pods deployed share the same configuration. If you need to deploy dedicated nodes types (for example dedicated master and data nodes), you can deploy multiple releases of this chart with different configurations while they share the same clusterName value.

For each Helm release, the nodes types can then be defined using roles value.

An example of Elasticsearch cluster using 2 different Helm releases for master, data and coordinating nodes can be found in examples/multi.

Coordinating nodes

Every node is implicitly a coordinating node. This means that a node that has an explicit empty list of roles will only act as a coordinating node.

When deploying coordinating-only node with Elasticsearch chart, it is required to define the empty list of roles in both roles value and node.roles settings:

roles: []

esConfig:
  elasticsearch.yml: |
    node.roles: []

More details in #1186 (comment)

Clustering and Node Discovery

This chart facilitates Elasticsearch node discovery and services by creating two Service definitions in Kubernetes, one with the name $clusterName-$nodeGroup and another named $clusterName-$nodeGroup-headless. Only Ready pods are a part of the $clusterName-$nodeGroup service, while all pods ( Ready or not) are a part of $clusterName-$nodeGroup-headless.

If your group of master nodes has the default nodeGroup: master then you can just add new groups of nodes with a different nodeGroup and they will automatically discover the correct master. If your master nodes have a different nodeGroup name then you will need to set masterService to $clusterName-$masterNodeGroup.

The chart value for masterService is used to populate discovery.zen.ping.unicast.hosts , which Elasticsearch nodes will use to contact master nodes and form a cluster. Therefore, to add a group of nodes to an existing cluster, setting masterService to the desired Service name of the related cluster is sufficient.

How to deploy clusters with security (authentication and TLS) enabled?

This Helm chart can generate a [Kubernetes Secret][] or use an existing one to setup Elastic credentials.

This Helm chart can use existing [Kubernetes Secret][] to setup Elastic certificates for example. These secrets should be created outside of this chart and accessed using environment variables and volumes.

This chart is setting TLS and creating a certificate by default, but you can also provide your own certs as a K8S secret. An example of configuration for providing existing certificates can be found in examples/security.

How to migrate from helm/charts stable chart?

If you currently have a cluster deployed with the helm/charts stable chart you can follow the migration guide.

How to install plugins?

The recommended way to install plugins into our Docker images is to create a custom Docker image.

The Dockerfile would look something like:

ARG elasticsearch_version
FROM docker.elastic.co/elasticsearch/elasticsearch:${elasticsearch_version}

RUN bin/elasticsearch-plugin install --batch repository-gcs

And then updating the image in values to point to your custom image.

There are a couple reasons we recommend this.

1. Tying the availability of Elasticsearch to the download service to install plugins is not a great idea or something that we recommend. Especially in Kubernetes where it is normal and expected for a container to be moved to another host at random times.
2. Mutating the state of a running Docker image (by installing plugins) goes against best practices of containers and immutable infrastructure.

How to use the keystore?

Basic example

Create the secret, the key name needs to be the keystore key path. In this example we will create a secret from a file and from a literal string.

kubectl create secret generic encryption-key --from-file=xpack.watcher.encryption_key=./watcher_encryption_key
kubectl create secret generic slack-hook --from-literal=xpack.notification.slack.account.monitoring.secure_url='https://hooks.slack.com/services/asdasdasd/asdasdas/asdasd'

To add these secrets to the keystore:

keystore:
  - secretName: encryption-key
  - secretName: slack-hook

Multiple keys

All keys in the secret will be added to the keystore. To create the previous example in one secret you could also do:

kubectl create secret generic keystore-secrets --from-file=xpack.watcher.encryption_key=./watcher_encryption_key --from-literal=xpack.notification.slack.account.monitoring.secure_url='https://hooks.slack.com/services/asdasdasd/asdasdas/asdasd'

keystore:
  - secretName: keystore-secrets

Custom paths and keys

If you are using these secrets for other applications (besides the Elasticsearch keystore) then it is also possible to specify the keystore path and which keys you want to add. Everything specified under each keystore item will be passed through to the volumeMounts section for mounting the secret. In this example we will only add the slack_hook key from a secret that also has other keys. Our secret looks like this:

kubectl create secret generic slack-secrets --from-literal=slack_channel='#general' --from-literal=slack_hook='https://hooks.slack.com/services/asdasdasd/asdasdas/asdasd'

We only want to add the slack_hook key to the keystore at path xpack.notification.slack.account.monitoring.secure_url:

keystore:
  - secretName: slack-secrets
    items:
    - key: slack_hook
      path: xpack.notification.slack.account.monitoring.secure_url

You can also take a look at the config example which is used as part of the automated testing pipeline.

How to enable snapshotting?

1. Install your snapshot plugin into a custom Docker image following the how to install plugins guide.
2. Add any required secrets or credentials into an Elasticsearch keystore following the how to use the keystore guide.
3. Configure the snapshot repository as you normally would.
4. To automate snapshots you can use Snapshot Lifecycle Management or a tool like curator.

How to configure templates post-deployment?

You can use postStart lifecycle hooks to run code triggered after a container is created.

Here is an example of postStart hook to configure templates:

lifecycle:
  postStart:
    exec:
      command:
        - bash
        - -c
        - |
          #!/bin/bash
          # Add a template to adjust number of shards/replicas
          TEMPLATE_NAME=my_template
          INDEX_PATTERN="logstash-*"
          SHARD_COUNT=8
          REPLICA_COUNT=1
          ES_URL=http://localhost:9200
          while [[ "$(curl -s -o /dev/null -w '%{http_code}\n' $ES_URL)" != "200" ]]; do sleep 1; done
          curl -XPUT "$ES_URL/_template/$TEMPLATE_NAME" -H 'Content-Type: application/json' -d'{"index_patterns":['\""$INDEX_PATTERN"\"'],"settings":{"number_of_shards":'$SHARD_COUNT',"number_of_replicas":'$REPLICA_COUNT'}}'

Contributing

Please check CONTRIBUTING.md before any contribution or for any questions about our development and testing process.