"Adding nodes" instructions only work on localhost (#52677)

The introductory sections of the reference manual contains some simplified
instructions for adding a node to the cluster. Unfortunately they are a little
too simplified and only really work for clusters running on `localhost`. If you
try and follow these instructions for a distributed cluster then the new node
will, confusingly, auto-bootstrap itself into a distinct one-node cluster.

Multiple nodes running on localhost is a valid config, of course, but we should
spell out that these instructions are really only for experimentation and that
it takes a bit more work to add nodes to a distributed cluster. This commit
does so.

Also, the "important config" instructions for discovery say that you MUST set
`discovery.seed_hosts` whereas in fact it is fine to ignore this setting and
use a dynamic discovery mechanism instead. This commit weakens this statement
and links to the docs for dynamic discovery mechanisms.

Finally, this section is also overloaded with some technical details that are
not important for this context and are adequately covered elsewhere, and
completely fails to note that the default discovery port is 9300. This commit
addresses this.

docs/reference/modules/discovery/discovery-settings.asciidoc

@@ -4,19 +4,32 @@
 Discovery and cluster formation are affected by the following settings:
 
 `discovery.seed_hosts`::
-
-    Provides a list of master-eligible nodes in the cluster. Each value has the
-    format `host:port` or `host`, where `port` defaults to the setting
-    `transport.profiles.default.port`. Note that IPv6 hosts must be bracketed.
-    The default value is `["127.0.0.1", "[::1]"]`. See <<unicast.hosts>>.
++
+--
+Provides a list of the addresses of the master-eligible nodes in the cluster.
+May also be a single string containing the addresses separated by commas. Each
+address has the format `host:port` or `host`. The `host` is either a host name
+to be resolved by DNS, an IPv4 address, or an IPv6 address. IPv6 addresses
+must be enclosed in square brackets. If a host name resolves via DNS to multiple
+addresses, {es} uses all of them. DNS lookups are subject to
+<<networkaddress-cache-ttl,JVM DNS caching>>. If the `port` is not given then it
+is determined by checking the following settings in order:
+
+. `transport.profiles.default.port`
+. `transport.port`
+
+If neither of these is set then the default port is `9300`. The default value
+for `discovery.seed_hosts` is `["127.0.0.1", "[::1]"]`. See <<unicast.hosts>>.
+--
 
 `discovery.seed_providers`::
 
     Specifies which types of <<built-in-hosts-providers,seed hosts provider>>
     to use to obtain the addresses of the seed nodes used to start the
     discovery process. By default, it is the
-    <<settings-based-hosts-provider,settings-based seed hosts provider>>.
-    
+    <<settings-based-hosts-provider,settings-based seed hosts provider>> which
+    obtains the seed node addresses from the `discovery.seed_hosts` setting.
+
 `discovery.type`::
  
     Specifies whether {es} should form a multiple-node cluster. By default, {es}

docs/reference/setup/add-nodes.asciidoc

@@ -25,13 +25,19 @@ green.
 
 image::setup/images/elas_0204.png["A cluster with three nodes"]
 
-To add a node to a cluster:
+You can run multiple nodes on your local machine in order to experiment with how
+an {es} cluster of multiple nodes behaves. To add a node to a cluster running on
+your local machine:
 
 . Set up a new {es} instance.
-. Specify the name of the cluster in its `cluster.name` attribute. For example,
-to add a node to the `logging-prod` cluster, set `cluster.name: "logging-prod"`
-in `elasticsearch.yml`.
+. Specify the name of the cluster with the `cluster.name` setting in
+`elasticsearch.yml`. For example, to add a node to the `logging-prod` cluster,
+add the line `cluster.name: "logging-prod"` to `elasticsearch.yml`.
 . Start {es}. The node automatically discovers and joins the specified cluster.
 
+To add a node to a cluster running on multiple machines, you must also
+<<unicast.hosts,set `discovery.seed_hosts`>> so that the new node can discover
+the rest of its cluster.
+
 For more information about discovery and shard allocation, see
 <<modules-discovery>> and <<modules-cluster>>.

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

@@ -14,19 +14,20 @@ each other and elect a master node.
 
 Out of the box, without any network configuration, Elasticsearch will bind to
 the available loopback addresses and will scan local ports 9300 to 9305 to try
-to connect to other nodes running on the same server. This provides an auto-
-clustering experience without having to do any configuration.
+to connect to other nodes running on the same server. This provides an
+auto-clustering experience without having to do any configuration.
 
-When you want to form a cluster with nodes on other hosts, you must use the
+When you want to form a cluster with nodes on other hosts, you should use the
 `discovery.seed_hosts` setting to provide a list of other nodes in the cluster
 that are master-eligible and likely to be live and contactable in order to seed
 the <<modules-discovery-hosts-providers,discovery process>>. This setting
-should normally contain the addresses of all the master-eligible nodes in the
-cluster.  This setting contains either an array of hosts or a comma-delimited
-string. Each value should be in the form of `host:port` or `host` (where `port`
-defaults to the setting `transport.profiles.default.port` falling back to
-`transport.port` if not set). Note that IPv6 hosts must be bracketed. The
-default for this setting is `127.0.0.1, [::1]`.
+should be a list of the addresses of all the master-eligible nodes in the
+cluster. Each address can be either an IP address or a hostname which resolves
+to one or more IP addresses via DNS.
+
+If your master-eligible nodes do not have fixed names or addresses, use an
+<<built-in-hosts-providers,alternative hosts provider>> to find their addresses
+dynamically.
 
 [float]
 [[initial_master_nodes]]
@@ -50,16 +51,18 @@ discovery.seed_hosts:
    - 192.168.1.10:9300
    - 192.168.1.11 <1>
    - seeds.mydomain.com <2>
-cluster.initial_master_nodes: <3>
+   - [0:0:0:0:0:ffff:c0a8:10c]:9301 <3>
+cluster.initial_master_nodes: <4>
    - master-node-a
    - master-node-b
    - master-node-c
 --------------------------------------------------
-<1> The port will default to `transport.profiles.default.port` and fallback to
-    `transport.port` if not specified.
+<1> The port is optional and usually defaults to `9300`, but this default can
+    be <<built-in-hosts-providers,overridden>> by certain settings.
 <2> If a hostname resolves to multiple IP addresses then the node will attempt to
     discover other nodes at all resolved addresses.
-<3> The initial master nodes should be identified by their
+<3> IPv6 addresses must be enclosed in square brackets.
+<4> The initial master nodes should be identified by their
     <<node.name,`node.name`>>, which defaults to their 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