From 417004918fe00a79196c86620ecf867808f3b3f9 Mon Sep 17 00:00:00 2001 From: David Turner Date: Tue, 19 Apr 2022 07:54:43 +0100 Subject: [PATCH] More docs re. removing cluster.initial_master_nodes (#85948) Ensures that on every page of the docs that mentions `cluster.initial_master_nodes` also mentions that this setting must be removed after bootstrapping completes. --- docs/reference/modules/discovery.asciidoc | 4 +--- docs/reference/modules/discovery/bootstrapping.asciidoc | 5 +++-- .../modules/discovery/discovery-settings.asciidoc | 8 +++++--- docs/reference/setup/bootstrap-checks.asciidoc | 8 ++++++++ .../setup/important-settings/discovery-settings.asciidoc | 7 ++++--- 5 files changed, 21 insertions(+), 11 deletions(-) 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..bc3b4f3d47c89 100644 --- a/docs/reference/modules/discovery/discovery-settings.asciidoc +++ b/docs/reference/modules/discovery/discovery-settings.asciidoc @@ -43,9 +43,11 @@ 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 328541e2ab918..c4b6206c3b8cf 100644 --- a/docs/reference/setup/bootstrap-checks.asciidoc +++ b/docs/reference/setup/bootstrap-checks.asciidoc @@ -252,3 +252,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] --------------------------------------------------