diff --git a/docs/reference/modules/discovery.asciidoc b/docs/reference/modules/discovery.asciidoc index 4fb8783f6f921..8b3d01a65e362 100644 --- a/docs/reference/modules/discovery.asciidoc +++ b/docs/reference/modules/discovery.asciidoc @@ -32,9 +32,7 @@ formation: themselves. As this auto-bootstrapping is <>, running a node in <> requires bootstrapping to be - explicitly configured via the - <>. + <>. <>:: diff --git a/docs/reference/modules/discovery/bootstrapping.asciidoc b/docs/reference/modules/discovery/bootstrapping.asciidoc index b1d9d74978ca3..f0f7b99fa5023 100644 --- a/docs/reference/modules/discovery/bootstrapping.asciidoc +++ b/docs/reference/modules/discovery/bootstrapping.asciidoc @@ -31,8 +31,9 @@ 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. It should not be set for master-ineligible -nodes, master-eligible nodes joining an existing cluster, or cluster restarts. +remove this 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 diff --git a/docs/reference/modules/discovery/discovery-settings.asciidoc b/docs/reference/modules/discovery/discovery-settings.asciidoc index 8d7c3a18db7c0..349013ca4a92f 100644 --- a/docs/reference/modules/discovery/discovery-settings.asciidoc +++ b/docs/reference/modules/discovery/discovery-settings.asciidoc @@ -43,9 +43,13 @@ setting, see <>. `cluster.initial_master_nodes`:: (<>) -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. 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 <>. [discrete] ==== Expert settings diff --git a/docs/reference/setup/bootstrap-checks.asciidoc b/docs/reference/setup/bootstrap-checks.asciidoc index 21c5ef6544890..d81c4a4e92dd2 100644 --- a/docs/reference/setup/bootstrap-checks.asciidoc +++ b/docs/reference/setup/bootstrap-checks.asciidoc @@ -253,3 +253,11 @@ properties: - `discovery.seed_hosts` - `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. diff --git a/docs/reference/setup/important-settings/discovery-settings.asciidoc b/docs/reference/setup/important-settings/discovery-settings.asciidoc index a96a01121a0de..c9ac91bdd42b2 100644 --- a/docs/reference/setup/important-settings/discovery-settings.asciidoc +++ b/docs/reference/setup/important-settings/discovery-settings.asciidoc @@ -59,9 +59,10 @@ 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. -IMPORTANT: After the cluster forms successfully for the first time, remove the `cluster.initial_master_nodes` setting from each nodes' -configuration. Do not use this setting when -restarting a cluster or adding a new node to an existing cluster. +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. [source,yaml] --------------------------------------------------