Deployment

How Elasticsearch is packaged and how a real deployment is bootstrapped.

Packaging

The distribution/ tree builds a release artifact for each supported channel:

distribution/
├── archives/
│   ├── linux-tar/, darwin-tar/, windows-zip/, freebsd-tar/        Tarballs
│   └── ...
├── packages/                                                       deb / rpm
├── docker/                                                         Container images (Wolfi-based)
├── tools/                                                          bin/ shell tools (server-cli, plugin-cli, keystore-cli, ...)
└── src/config/                                                     Default config files

Build a tarball:

./gradlew :distribution:archives:linux-tar:assemble

Build the Docker image:

./gradlew :distribution:docker:assemble

Each artifact carries:

• The Elasticsearch JAR set.
• The bundled JDK (configurable via ES_JAVA_HOME).
• All modules/.
• The default config/ (elasticsearch.yml, jvm.options, log4j2.properties).
• All shell scripts under bin/.

External plugins (plugins/) are installed by the user via bin/elasticsearch-plugin install.

Topology

A production cluster is a heterogeneous set of nodes with different roles:

graph TD
  subgraph master_eligible
    M1[master 1]
    M2[master 2]
    M3[master 3]
  end
  subgraph hot_data
    H1[hot 1]
    H2[hot 2]
  end
  subgraph warm_data
    W1[warm]
  end
  subgraph cold_data
    C1[cold]
  end
  subgraph frozen_data
    F1[frozen]
  end
  subgraph ml_nodes
    ML1[ml 1]
  end
  Client --> Coord[coordinating-only nodes]
  Coord --> M1
  Coord --> H1
  Coord --> H2
  M1 --- M2
  M1 --- M3

Common deployment patterns:

• Small (1–5 nodes): all roles on every node.
• Tiered: dedicated master, hot data, warm data, cold data, frozen data, plus ml/transform/coordinating-only as needed.
• Stateless / serverless: data nodes are caches; the durable copy is in object storage. See Stateless.

First-start auto-configuration

When a node starts for the first time on a fresh data directory:

1. Generate a self-signed CA + node certificate.
2. Create the elastic user with a randomly-generated password.
3. Print the password and an enrollment token for Kibana.
4. Configure the keystore.

The wizard lives in distribution/tools/server-cli/ and the security plugin's CLI (x-pack/plugin/security/cli/).

Cluster bring-up

Two non-trivial steps:

1. Initial voting configuration — set cluster.initial_master_nodes for the very first master election. Remove afterwards.
2. Discovery — configure discovery.seed_hosts (or use a discovery plugin like discovery-ec2).

After the first election, the voting configuration self-manages.

CI and release pipeline

• Buildkite pipelines define the release process. Each major/minor branch has its own pipeline definitions under .buildkite/.
• Backport bot opens backport PRs to active branches per .backportrc.json.
• Release tags (v9.3.3, v9.2.8, etc.) are produced by a release Buildkite job that builds artifacts, signs them, and publishes them to artifacts.elastic.co.

Configuration files

File	Purpose
config/elasticsearch.yml	Cluster + node config
config/jvm.options + jvm.options.d/	Heap, GC, file-descriptor settings
config/log4j2.properties	Logger config
config/users / users_roles	File-realm users (security)
config/role_mapping.yml	External-realm role mapping
config/elasticsearch.keystore	Encrypted secrets

Reserved state and operator privileges

config/operator/settings.json is the reserved-state mechanism: settings written there override anything set via _cluster/settings and cannot be modified by API, allowing cloud operators to lock down configuration even from cluster admins.

Upgrades

• Rolling upgrade: stop one node, upgrade, restart. Cluster stays available; mixed-version is supported within a major.
• Full-cluster restart: required across some major boundaries.
• BWC tested in CI: qa/full-cluster-restart and qa/rolling-upgrade plus the :bwc Gradle subprojects.

Stateless deployments

Stateless mode is the topology behind Elastic Cloud Serverless: data nodes are caches over object storage. Commits are durable in S3/GCS/Azure as soon as they succeed, so a node failure costs only a cache rebuild. See Stateless.