Further clarify cluster.initial_master_nodes (#41179)

The following phrase causes confusion:

> Alternatively the IP addresses or hostnames (if node name defaults to the
> host name) can be used.

This change clarifies the conditions under which you can use a hostname, and
adds an anchor to the note introduced in (#41137) so we can link directly to it
in conversations with users.

Author: DaveCTurner

docs/reference/modules/discovery/bootstrapping.asciidoc

@@ -9,16 +9,21 @@ up: nodes that have already joined a cluster store this information in their
 data folder and freshly-started nodes that are joining an existing 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>>. 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.
+The initial set of master-eligible nodes is defined in the
+<<initial_master_nodes,`cluster.initial_master_nodes` setting>>. This is a list
+of the <<node.name,node names>> or IP addresses of the master-eligible nodes in
+the new cluster. If you do not configure `node.name` then it is set to the
+node's hostname, so in this case you can use hostnames in
+`cluster.initial_master_nodes` too.
+
+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.
 
 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
@@ -42,10 +47,9 @@ cluster.initial_master_nodes:
   - master-c
 --------------------------------------------------
 
-Alternatively the IP addresses or hostnames (<<node.name,if node name defaults
-to the host name>>) can be used. If there is more than one Elasticsearch node
-with the same IP address or hostname then the transport ports must also be given
-to specify exactly which node is meant:
+You can use a mix of IP addresses and node names too. If there is more than one
+Elasticsearch node with the same IP address then the transport port must also
+be given to specify exactly which node is meant:
 
 [source,yaml]
 --------------------------------------------------
@@ -56,14 +60,23 @@ cluster.initial_master_nodes:
   - master-node-hostname
 --------------------------------------------------
 
+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 -Ecluster.initial_master_nodes=master-a,master-b,master-c
+--------------------------------------------------
+
 [NOTE]
 ==================================================
 
-The node names used in this list must exactly match the `node.name` properties
-of the nodes. By default the node name is set to the machine's hostname which
-may or may not be fully-qualified depending on your system configuration. If
-each node name is a fully-qualified domain name such as `master-a.example.com`
-then you must use fully-qualified domain names in the
+[[modules-discovery-bootstrap-cluster-fqdns]] The node names used in the
+`cluster.initial_master_nodes` list must exactly match the `node.name`
+properties of the nodes. By default the node name is set to the machine's
+hostname which may or may not be fully-qualified depending on your system
+configuration. If each node name is a fully-qualified domain name such as
+`master-a.example.com` then you must use fully-qualified domain names in the
 `cluster.initial_master_nodes` list too; conversely if your node names are bare
 hostnames (without the `.example.com` suffix) then you must use bare hostnames
 in the `cluster.initial_master_nodes` list. If you use a mix of fully-qualifed
@@ -81,18 +94,11 @@ bootstrap a cluster: have discovered [{master-b.example.com}{...
 
 This message shows the node names `master-a.example.com` and
 `master-b.example.com` as well as the `cluster.initial_master_nodes` entries
-`master-a` and `master-b`, and it is apparent that they do not match exactly.
+`master-a` and `master-b`, and it is clear from this message that they do not
+match exactly.
 
 ==================================================
 
-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 -Ecluster.initial_master_nodes=master-a,master-b,master-c
---------------------------------------------------
-
 [float]
 ==== Choosing a cluster name
 

docs/reference/setup/important-settings/discovery-settings.asciidoc

@@ -58,15 +58,17 @@ cluster.initial_master_nodes:
     `transport.port` if not specified.
 <2> If a hostname resolves to multiple IP addresses then the node will attempt to
     discover other nodes at all resolved addresses.
-<3> Initial master nodes can be identified by their <<node.name,`node.name`>>.
-    Make sure that the value here matches the `node.name` exactly. If you use a
-    fully-qualified domain name such as `master-node-a.example.com` for your
+<3> Initial master nodes can be identified by their <<node.name,`node.name`>>,
+    which defaults to the hostname. Make sure that the value in
+    `cluster.initial_master_nodes` matches the `node.name` exactly. If you use
+    a fully-qualified domain name such as `master-node-a.example.com` for your
     node names then you must use the fully-qualified name in this list;
     conversely if `node.name` is a bare hostname without any trailing
     qualifiers then you must also omit the trailing qualifiers in
     `cluster.initial_master_nodes`.
 <4> Initial master nodes can also be identified by their IP address.
-<5> If multiple master nodes share an IP address then the port must be used to
-    disambiguate them.
+<5> If multiple master nodes share an IP address then the transport port must
+    be used to distinguish between them.
 
-For more information, see <<modules-discovery-settings>>.
+For more information, see <<modules-discovery-bootstrap-cluster>> and
+<<modules-discovery-settings>>.