How to configure Elasticsearch cluster bootstrap settings

Bootstrap settings determine how a brand-new Elasticsearch cluster elects its first master-eligible node and commits a single cluster UUID. Correct values prevent multiple isolated clusters from forming during the initial rollout and keep the first election predictable.

During the first startup with an empty data path, Elasticsearch uses node discovery to locate peers and uses cluster.initial_master_nodes to define the initial voting configuration. The entries must match the exact node.name values of the master-eligible nodes that are allowed to participate in the first election.

The cluster.initial_master_nodes setting is only required for first cluster formation and should be removed once the cluster is healthy. Leaving it in place increases the risk of accidental re-bootstrap when bringing up fresh nodes, especially when a node starts with a cleared data directory or a new deployment image with no existing cluster state.

1. Open the Elasticsearch configuration file on a master-eligible node.

   $ sudo nano /etc/elasticsearch/elasticsearch.yml

2. Add the discovery and bootstrap settings for first cluster formation.

   cluster.name: search-cluster
   node.name: node-01
   
   discovery.seed_hosts:
     - node-01
     - node-02
     - node-03
   
   cluster.initial_master_nodes:
     - node-01
     - node-02
     - node-03

   The cluster.initial_master_nodes list must match the exact node.name values of the master-eligible nodes. The discovery.seed_hosts list must contain resolvable hostnames or reachable IP addresses.

   Setting cluster.initial_master_nodes on nodes joining an existing cluster can cause the node to bootstrap an unintended cluster.

3. Apply the same cluster.initial_master_nodes list on the remaining master-eligible nodes.

   Keep the list identical across nodes and change only the local node.name value.

4. Restart the Elasticsearch service to apply the configuration.

   $ sudo systemctl restart elasticsearch

   Related: How to manage the Elasticsearch service with systemctl in Linux

5. Verify the cluster health reports the expected node count.

   $ curl -s "http://localhost:9200/_cluster/health?pretty"
   {
     "cluster_name" : "search-cluster",
     "status" : "green",
     "timed_out" : false,
     "number_of_nodes" : 3,
     "number_of_data_nodes" : 3
   ##### snipped #####
   }

   Secured clusters may require HTTPS and authentication, for example:

   $ curl --silent --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic "https://localhost:9200/_cluster/health?pretty"

6. List the nodes to confirm the expected names and master election state.

   $ curl -s "http://localhost:9200/_cat/nodes?v"
   ip         heap.percent ram.percent cpu load_1m load_5m load_15m node.role master name
   192.0.2.40           62          69  25    4.26    2.64     2.00 cdfhilmrstw -      node-01
   192.0.2.41           35          69  17    4.26    2.64     2.00 cdfhilmrstw *      node-02
   192.0.2.42           49          69   6    4.26    2.64     2.00 cdfhilmrstw -      node-03

7. Remove the cluster.initial_master_nodes line from the configuration file on all nodes.

   cluster.name: search-cluster
   node.name: node-01
   
   discovery.seed_hosts:
     - node-01
     - node-02
     - node-03

   Remove cluster.initial_master_nodes only after the cluster forms and remains stable.

8. Restart the Elasticsearch service after removing the bootstrap setting.

   $ sudo systemctl restart elasticsearch

   Related: How to manage the Elasticsearch service with systemctl in Linux

9. Re-check cluster health to confirm normal operation.

   $ curl -s "http://localhost:9200/_cluster/health?pretty"
   {
     "cluster_name" : "search-cluster",
     "status" : "green",
     "timed_out" : false,
     "number_of_nodes" : 3,
     "number_of_data_nodes" : 3
   ##### snipped #####
   }