diff --git a/docs/reference/modules/discovery/bootstrapping.asciidoc b/docs/reference/modules/discovery/bootstrapping.asciidoc index 81ac3f6cc4cdc..5120c1d17e69b 100644 --- a/docs/reference/modules/discovery/bootstrapping.asciidoc +++ b/docs/reference/modules/discovery/bootstrapping.asciidoc @@ -5,7 +5,7 @@ Starting an Elasticsearch cluster for the very first time requires the initial set of <> 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 first time a cluster starts up. -Freshly-started nodes that are joining a running cluster obtain this +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 @@ -27,17 +27,20 @@ node: if it is not possible to use the `node.name` of the node and there are multiple nodes sharing a single IP address. +Do not set `cluster.initial_master_nodes` on master-ineligible nodes. + [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 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. +from each node's configuration and never set it again for this cluster. Do not +configure this setting on nodes joining an existing cluster. Do not configure +this setting on nodes which are restarting. Do not configure this setting when +performing a full-cluster restart. + +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 diff --git a/docs/reference/modules/discovery/discovery-settings.asciidoc b/docs/reference/modules/discovery/discovery-settings.asciidoc index 401d1e7206d35..daf84f0292c12 100644 --- a/docs/reference/modules/discovery/discovery-settings.asciidoc +++ b/docs/reference/modules/discovery/discovery-settings.asciidoc @@ -46,8 +46,11 @@ setting, see <>. Sets the initial set of master-eligible nodes in a brand-new cluster. By default this list is empty, meaning that this node expects to join a cluster that has already been bootstrapped. Remove this setting once the cluster has -formed. Do not use this setting when restarting nodes or when adding new nodes -to an existing cluster. See <>. +formed, and never set it again for this cluster. Do not configure this setting +on master-ineligible nodes. Do not configure this setting on nodes joining an +existing cluster. Do not configure this setting on nodes which are restarting. +Do not configure this setting when performing a full-cluster restart. See +<>. [discrete] ==== Expert settings diff --git a/docs/reference/setup/bootstrap-checks.asciidoc b/docs/reference/setup/bootstrap-checks.asciidoc index 20f93496934f7..64977ae4e4611 100644 --- a/docs/reference/setup/bootstrap-checks.asciidoc +++ b/docs/reference/setup/bootstrap-checks.asciidoc @@ -245,10 +245,9 @@ properties: - `discovery.seed_providers` - `cluster.initial_master_nodes` -Note that you should remove `cluster.initial_master_nodes` from the -configuration after the cluster has started for the first time. Do not use this -setting when restarting nodes or when adding new nodes to an existing cluster. -Instead, configure `discovery.seed_hosts` or `discovery.seed_providers`. If you -do not need any discovery configuration, for instance if running a single-node -cluster, set `discovery.seed_hosts: []` to disable discovery and satisfy this -bootstrap check. +Note that you must <> after the cluster has started for the +first time. Instead, configure `discovery.seed_hosts` or +`discovery.seed_providers`. If you do not need any discovery configuration, for +instance if running a single-node cluster, set `discovery.seed_hosts: []` to +disable discovery and satisfy this bootstrap check. diff --git a/docs/reference/setup/important-settings/discovery-settings.asciidoc b/docs/reference/setup/important-settings/discovery-settings.asciidoc index 180121b93206a..acd10a045c6c0 100644 --- a/docs/reference/setup/important-settings/discovery-settings.asciidoc +++ b/docs/reference/setup/important-settings/discovery-settings.asciidoc @@ -53,16 +53,18 @@ first election. In <>, with no discovery settings configured, this step is performed automatically by the nodes themselves. -Because auto-bootstrapping is <>, when starting a new cluster in production -mode, you must explicitly list the master-eligible nodes whose votes should be -counted in the very first election. You set this list using the -`cluster.initial_master_nodes` setting. +Because auto-bootstrapping is <>, +when starting a new cluster in production mode, you must explicitly list the +master-eligible nodes whose votes should be counted in the very first election. +You set this list using the `cluster.initial_master_nodes` setting on every +master-eligible node. Do not configure this setting on master-ineligible nodes. IMPORTANT: After the cluster forms successfully for the first time, remove the -`cluster.initial_master_nodes` setting from each node's configuration. Do not -use this setting when restarting a cluster or adding a new node to an existing -cluster. +`cluster.initial_master_nodes` setting from each node's configuration and never +set it again for this cluster. Do not configure this setting on nodes joining +an existing cluster. Do not configure this setting on nodes which are +restarting. Do not configure this setting when performing a full-cluster +restart. See <>. [source,yaml] --------------------------------------------------