Browse Source

More bootstrap docs tweaks (#47809)

Clarifies not to set `cluster.initial_master_nodes` on nodes that are joining
an existing cluster.

Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
David Turner 6 years ago
parent
commit
9e30a57ca5

+ 7 - 11
docs/reference/modules/discovery/bootstrapping.asciidoc

@@ -4,11 +4,11 @@
 Starting an Elasticsearch cluster for the very first time requires the initial
 set of <<master-node,master-eligible nodes>> to be explicitly defined on one or
 more of the master-eligible nodes in the cluster. This is known as _cluster
-bootstrapping_.  This is only required the very first time the cluster starts
-up: nodes that have already joined a cluster store this information in their
-data folder for use in a <<restart-upgrade,full cluster restart>>, and
-freshly-started nodes that are joining a running cluster obtain this
-information from the cluster's elected master.
+bootstrapping_. This is only required the first time a cluster starts up: nodes
+that have already joined a cluster store this information in their data folder
+for use in a <<restart-upgrade,full cluster restart>>, and freshly-started nodes
+that are joining a running cluster obtain this information from the cluster's
+elected master.
 
 The initial set of master-eligible nodes is defined in the
 <<initial_master_nodes,`cluster.initial_master_nodes` setting>>. This should be
@@ -30,12 +30,8 @@ node:
 
 When you start a master-eligible node, you can provide this setting on the
 command line or in the `elasticsearch.yml` file. After the cluster has formed,
-this setting is no longer required and is ignored. It need not be set on
-master-ineligible nodes, nor on master-eligible nodes that are started to join
-an existing cluster. Note that master-eligible nodes should use storage that
-persists across restarts. If they do not, and `cluster.initial_master_nodes` is
-set, and a full cluster restart occurs, then another brand-new cluster will
-form and this may result in data loss.
+this setting is no longer required. It should not be set for master-ineligible
+nodes, master-eligible nodes joining an existing cluster, or cluster restarts.
 
 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

+ 3 - 2
docs/reference/setup/important-settings/discovery-settings.asciidoc

@@ -40,8 +40,9 @@ settings configured, this step is automatically performed by the nodes
 themselves. As this auto-bootstrapping is <<modules-discovery-quorums,inherently
 unsafe>>, when you start a brand new cluster in <<dev-vs-prod-mode,production
 mode>>, you must explicitly list the master-eligible nodes whose votes should be
-counted in the very first election.  This list is set using the
-`cluster.initial_master_nodes` setting.
+counted in the very first election. This list is set using the
+`cluster.initial_master_nodes` setting. You should not use this setting when
+restarting a cluster or adding a new node to an existing cluster.
 
 [source,yaml]
 --------------------------------------------------