Browse Source

Bootstrapping docs clarifications (#94977)

Explains why you should remove `cluster.initial_master_nodes`, and
rewords some of the other sections a little for (subjectively) improved
readability.
David Turner 2 years ago
parent
commit
f0989404ab
1 changed files with 27 additions and 23 deletions
  1. 27 23
      docs/reference/modules/discovery/bootstrapping.asciidoc

+ 27 - 23
docs/reference/modules/discovery/bootstrapping.asciidoc

@@ -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]
 --------------------------------------------------
@@ -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