Skip to content

Commit

Permalink
Bootstrapping docs clarifications (elastic#94977)
Browse files Browse the repository at this point in the history
Explains why you should remove `cluster.initial_master_nodes`, and
rewords some of the other sections a little for (subjectively) improved
readability.
  • Loading branch information
DaveCTurner authored Apr 3, 2023
1 parent 092fa8d commit f098940
Showing 1 changed file with 27 additions and 23 deletions.
50 changes: 27 additions & 23 deletions docs/reference/modules/discovery/bootstrapping.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -29,27 +29,33 @@ node:
if it is not possible to use the `node.name` of the node and there are
multiple nodes sharing a single IP address.

When you start a master-eligible node, you can provide this setting on the
command line or in the `elasticsearch.yml` file.

IMPORTANT: After the cluster has formed, remove the `cluster.initial_master_nodes`
setting from each node's configuration. It should not be set for
master-ineligible nodes, master-eligible nodes joining an existing cluster, or
when restarting one or more nodes.

It is technically sufficient to set `cluster.initial_master_nodes` on a single
master-eligible node in the cluster, and only to mention that single node in the
setting's value, but this provides no fault tolerance before the cluster has
fully formed. It is therefore better to bootstrap using at least three
master-eligible nodes, each with a `cluster.initial_master_nodes` setting
containing all three nodes.
nodes which are restarting.
+
If you leave `cluster.initial_master_nodes` in place once the cluster has
formed then there is a risk that a future misconfiguration may result in
bootstrapping a new cluster alongside your existing cluster. It may not be
possible to recover from this situation without losing data.

The simplest way to create a new cluster is for you to select one of your
master-eligible nodes that will bootstrap itself into a single-node cluster,
which all the other nodes will then join. This simple approach is not resilient
to failures until the other master-eligible nodes have joined the cluster. For
example, if you have a master-eligible node with <<node-name,node name>>
`master-a` then configure it as follows (omitting
`cluster.initial_master_nodes` from the configuration of all other nodes):

WARNING: You must set `cluster.initial_master_nodes` to the same list of nodes
on each node on which it is set in order to be sure that only a single cluster
forms during bootstrapping and therefore to avoid the risk of data loss.
[source,yaml]
--------------------------------------------------
cluster.initial_master_nodes: master-a
--------------------------------------------------

For a cluster with 3 master-eligible nodes (with <<node-name,node names>>
`master-a`, `master-b` and `master-c`) the configuration will look as follows:
For fault-tolerant cluster bootstrapping, use all the master-eligible nodes.
For instance, if your cluster has 3 master-eligible nodes with <<node-name,node
names>> `master-a`, `master-b` and `master-c` then configure them all as
follows:

[source,yaml]
--------------------------------------------------
Expand All @@ -59,13 +65,11 @@ cluster.initial_master_nodes:
- master-c
--------------------------------------------------

Like all node settings, it is also possible to specify the initial set of master
nodes on the command-line that is used to start Elasticsearch:

[source,bash]
--------------------------------------------------
bin/elasticsearch -E cluster.initial_master_nodes=master-a,master-b,master-c
--------------------------------------------------
IMPORTANT: You must set `cluster.initial_master_nodes` to the same list of
nodes on each node on which it is set in order to be sure that only a single
cluster forms during bootstrapping. If `cluster.initial_master_nodes` varies
across the nodes on which it is set then you may bootstrap multiple clusters.
It is usually not possible to recover from this situation without losing data.

[[modules-discovery-bootstrap-cluster-fqdns]]
.Node name formats must match
Expand Down

0 comments on commit f098940

Please sign in to comment.