From f0989404ab2dbb9dcedc7be5451decfb003fd528 Mon Sep 17 00:00:00 2001 From: David Turner Date: Mon, 3 Apr 2023 14:43:12 +0100 Subject: [PATCH] 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. --- .../modules/discovery/bootstrapping.asciidoc | 48 ++++++++++--------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/docs/reference/modules/discovery/bootstrapping.asciidoc b/docs/reference/modules/discovery/bootstrapping.asciidoc index 8450a84f2d6e..850b7404a8d1 100644 --- a/docs/reference/modules/discovery/bootstrapping.asciidoc +++ b/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. +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. -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. +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 <> +`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 <> -`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 <> `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