Documentation for file-based discovery plugin (#20462)

Documentation for file-based discovery plugin.

Closes #20458

docs/plugins/discovery-file.asciidoc

@@ -0,0 +1,93 @@
+[[discovery-file]]
+=== File-Based Discovery Plugin
+
+The file-based discovery plugin uses a list of hosts/ports in a `unicast_hosts.txt` file 
+in the `config/discovery-file` directory for unicast discovery.
+
+[[discovery-file-install]]
+[float]
+==== Installation
+
+This plugin can be installed using the plugin manager:
+
+[source,sh]
+----------------------------------------------------------------
+sudo bin/elasticsearch-plugin install discovery-file
+----------------------------------------------------------------
+
+The plugin must be installed on every node in the cluster, and each node must
+be restarted after installation. Note that installing the plugin will add a
+`discovery-file` directory to the `config` folder, and a default `unicast_hosts.txt`
+file that must be edited with the correct unicast hosts list before starting the node.
+
+[[discovery-file-remove]]
+[float]
+==== Removal
+
+The plugin can be removed with the following command:
+
+[source,sh]
+----------------------------------------------------------------
+sudo bin/elasticsearch-plugin remove discovery-file
+----------------------------------------------------------------
+
+The node must be stopped before removing the plugin.
+
+[[discovery-file-usage]]
+[float]
+==== Using the file-based discovery plugin
+
+The file-based discovery plugin provides the ability to specify the 
+unicast hosts list through a simple `unicast_hosts.txt` file that can
+be dynamically updated at any time.  The discovery type for this plugin
+is still the default `zen` plugin, so no changes are required to the 
+`elasticsearch.yml` config file.  This plugin simply provides a facility
+to supply the unicast hosts list for zen discovery through an external
+file that can be updated at any time by a side process.  
+
+For example, this gives a convenient mechanism for an Elasticsearch instance 
+that is  run in docker containers to be dynamically supplied a list of IP 
+addresses to connect to for zen discovery when those IP addresses may not be 
+known at node startup.  
+
+Note that the file-based discovery plugin is meant to augment the unicast
+hosts list in `elasticsearch.yml` (if specified), not replace it.  Therefore,
+if there are valid unicast host entries in `discovery.zen.ping.unicast.hosts`,
+they will be used in addition to those supplied in `unicast_hosts.txt`.
+
+Anytime a change is made to the `unicast_hosts.txt` file, even as Elasticsearch
+continues to run, the new changes will be picked up by the plugin and the
+new hosts list will be used for the next pinging round for master election.
+
+Upon installation of the plugin, a default `unicast_hosts.txt` file will
+be found in the `$CONFIG_DIR/discovery-file` directory.  This default file
+will contain some comments about what the file should contain.  All comments
+for this file must appear on their lines starting with `#` (i.e. comments
+cannot start in the middle of a line).
+
+[[discovery-file-format]]
+[float]
+==== unicast_hosts.txt file format
+
+The format of the file is to specify one unicast host entry per line.  
+Each unicast host entry consists of the host (host name or IP address) and
+an optional transport port number.  If the port number is specified, is must 
+come immediately after the host (on the same line) separated by a `:`. 
+If the port number is not specified, a default value of 9300 is used.  
+
+For example, this is an example of `unicast_hosts.txt` for a cluster with
+four nodes that participate in unicast discovery, some of which are not
+running on the default port:
+
+[source,txt]
+----------------------------------------------------------------
+10.10.10.5
+10.10.10.6:9305
+10.10.10.5:10005
+# an IPv6 address
+[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:9301
+----------------------------------------------------------------
+
+Host names are allowed instead of IP addresses (similar to 
+`discovery.zen.ping.unicast.hosts`), and IPv6 addresses must be 
+specified in brackets with the port coming after the brackets. 

docs/plugins/discovery.asciidoc

@@ -21,6 +21,10 @@ The Azure Classic discovery plugin uses the Azure Classic API for unicast discov
 
 The Google Compute Engine discovery plugin uses the GCE API for unicast discovery.
 
+<<discovery-file,File-based discovery>>::
+
+The File-based discovery plugin allows providing the unicast hosts list through a dynamically updatable file.
+
 [float]
 ==== Community contributed discovery plugins
 
@@ -37,3 +41,5 @@ include::discovery-azure-classic.asciidoc[]
 
 include::discovery-gce.asciidoc[]
 
+include::discovery-file.asciidoc[]
+