Move file-based discovery to core (#33241)

Today we support a static list of seed hosts in core Elasticsearch, and allow a
dynamic list of seed hosts to be provided via a file using the `discovery-file`
plugin. In fact the ability to provide a dynamic list of seed hosts is
increasingly useful, so this change moves this functionality to core
Elasticsearch to avoid the need for a plugin.

Furthermore, in order to start up nodes in integration tests we currently
assign a known port to each node before startup, which unfortunately sometimes
fails if another process grabs the selected port in the meantime. By moving the
`discovery-file` functionality into the core product we can use it to avoid
this race.

This change also moves the expected path to the file from
`$ES_PATH_CONF/discovery-file/unicast_hosts.txt` to
`$ES_PATH_CONF/unicast_hosts.txt`. An example of this file is not included in
distributions.

For BWC purposes the plugin still exists, but does nothing more than create the
example file in the old location, and issue a warning when it is used. We also
continue to support the old location for the file, but warn about its
deprecation.

Relates #29244
Closes #33030

docs/plugins/discovery-file.asciidoc

@@ -1,71 +1,14 @@
 [[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.
+The functionality provided by the `discovery-file` plugin is now available in
+Elasticsearch without requiring a plugin. This plugin still exists to ensure
+backwards compatibility, but it will be removed in a future version.
+
+On installation, this plugin creates a file at
+`$ES_PATH_CONF/discovery-file/unicast_hosts.txt` that comprises comments that
+describe how to use it. It is preferable not to install this plugin and instead
+to create this file, and its containing directory, using standard tools.
 
 :plugin_name: discovery-file
 include::install_remove.asciidoc[]
-
-[[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. To enable, add the following in `elasticsearch.yml`:
-
-[source,yaml]
-----
-discovery.zen.hosts_provider: 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/reference/modules/discovery/zen.asciidoc

@@ -1,13 +1,12 @@
 [[modules-discovery-zen]]
 === Zen Discovery
 
-The zen discovery is the built in discovery module for Elasticsearch and
-the default. It provides unicast discovery, but can be extended to
-support cloud environments and other forms of discovery.
+Zen discovery is the built-in, default, discovery module for Elasticsearch.  It
+provides unicast and file-based discovery, and can be extended to support cloud
+environments and other forms of discovery via plugins.
 
-The zen discovery is integrated with other modules, for example, all
-communication between nodes is done using the
-<<modules-transport,transport>> module.
+Zen discovery is integrated with other modules, for example, all communication
+between nodes is done using the <<modules-transport,transport>> module.
 
 It is separated into several sub modules, which are explained below:
 
@@ -15,86 +14,159 @@ It is separated into several sub modules, which are explained below:
 [[ping]]
 ==== Ping
 
-This is the process where a node uses the discovery mechanisms to find
-other nodes.
+This is the process where a node uses the discovery mechanisms to find other
+nodes.
+
+[float]
+[[discovery-seed-nodes]]
+==== Seed nodes
+
+Zen discovery uses a list of _seed_ nodes in order to start off the discovery
+process. At startup, or when electing a new master, Elasticsearch tries to
+connect to each seed node in its list, and holds a gossip-like conversation with
+them to find other nodes and to build a complete picture of the cluster. By
+default there are two methods for configuring the list of seed nodes: _unicast_
+and _file-based_.  It is recommended that the list of seed nodes comprises the
+list of master-eligible nodes in the cluster.
 
 [float]
 [[unicast]]
 ===== Unicast
 
-Unicast discovery requires a list of hosts to use that will act as gossip
-routers. These hosts can be specified as hostnames or IP addresses; hosts
-specified as hostnames are resolved to IP addresses during each round of
-pinging. Note that if you are in an environment where DNS resolutions vary with
-time, you might need to adjust your <<networkaddress-cache-ttl,JVM security
-settings>>.
+Unicast discovery configures a static list of hosts for use as seed nodes.
+These hosts can be specified as hostnames or IP addresses; hosts specified as
+hostnames are resolved to IP addresses during each round of pinging. Note that
+if you are in an environment where DNS resolutions vary with time, you might
+need to adjust your <<networkaddress-cache-ttl,JVM security settings>>.
 
-It is recommended that the unicast hosts list be maintained as the list of
-master-eligible nodes in the cluster.
+The list of hosts is set using the `discovery.zen.ping.unicast.hosts` static
+setting.  This is 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.tcp.port` if not set). Note that IPv6 hosts must be bracketed. The
+default for this setting is `127.0.0.1, [::1]`
 
-Unicast discovery provides the following settings with the `discovery.zen.ping.unicast` prefix:
+Additionally, the `discovery.zen.ping.unicast.resolve_timeout` configures the
+amount of time to wait for DNS lookups on each round of pinging. This is
+specified as a <<time-units, time unit>> and defaults to 5s.
 
-[cols="<,<",options="header",]
-|=======================================================================
-|Setting |Description
-|`hosts` |Either an array setting or a comma delimited setting. 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.tcp.port` if not set). Note that IPv6 hosts must be bracketed. Defaults to `127.0.0.1, [::1]`
-|`hosts.resolve_timeout` |The amount of time to wait for DNS lookups on each round of pinging. Specified as
-<<time-units, time units>>. Defaults to 5s.
-|=======================================================================
+Unicast discovery uses the <<modules-transport,transport>> module to perform the
+discovery.
 
-The unicast discovery uses the <<modules-transport,transport>> module to perform the discovery.
+[float]
+[[file-based-hosts-provider]]
+===== File-based
+
+In addition to hosts provided by the static `discovery.zen.ping.unicast.hosts`
+setting, it is possible to provide a list of hosts via an external file.
+Elasticsearch reloads this file when it changes, so that the list of seed nodes
+can change dynamically without needing to restart each node. For example, this
+gives a convenient mechanism for an Elasticsearch instance that is run in a
+Docker container to be dynamically supplied with a list of IP addresses to
+connect to for Zen discovery when those IP addresses may not be known at node
+startup.
+
+To enable file-based discovery, configure the `file` hosts provider as follows:
+
+```
+discovery.zen.hosts_provider: file
+```
+
+Then create a file at `$ES_PATH_CONF/unicast_hosts.txt` in
+<<discovery-file-format,the format described below>>. Any time a change is made
+to the `unicast_hosts.txt` file the new changes will be picked up by
+Elasticsearch and the new hosts list will be used.
+
+Note that the file-based discovery plugin augments the unicast hosts list in
+`elasticsearch.yml`: if there are valid unicast host entries in
+`discovery.zen.ping.unicast.hosts` then they will be used in addition to those
+supplied in `unicast_hosts.txt`.
+
+The `discovery.zen.ping.unicast.resolve_timeout` setting also applies to DNS
+lookups for nodes specified by address via file-based discovery. This is
+specified as a <<time-units, time unit>> and defaults to 5s.
+
+[[discovery-file-format]]
+[float]
+====== unicast_hosts.txt file format
+
+The format of the file is to specify one node entry per line.  Each node 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.
+
+It is also possible to add comments to this file. All comments must appear on
+their lines starting with `#` (i.e. comments cannot start in the middle of a
+line).
 
 [float]
 [[master-election]]
 ==== Master Election
 
-As part of the ping process a master of the cluster is either
-elected or joined to. This is done automatically. The
-`discovery.zen.ping_timeout` (which defaults to `3s`) determines how long the node
-will wait before deciding on starting an election or joining an existing cluster.
-Three pings will be sent over this timeout interval. In case where no decision can be
-reached after the timeout, the pinging process restarts.
-In slow or congested networks, three seconds might not be enough for a node to become
-aware of the other nodes in its environment before making an election decision.
-Increasing the timeout should be done with care in that case, as it will slow down the
-election process.
-Once a node decides to join an existing formed cluster, it
-will send a join request to the master (`discovery.zen.join_timeout`)
-with a timeout defaulting at 20 times the ping timeout.
-
-When the master node stops or has encountered a problem, the cluster nodes
-start pinging again and will elect a new master. This pinging round also
-serves as a protection against (partial) network failures where a node may unjustly
-think that the master has failed. In this case the node will simply hear from
-other nodes about the currently active master.
-
-If `discovery.zen.master_election.ignore_non_master_pings` is `true`, pings from nodes that are not master
-eligible (nodes where `node.master` is `false`) are ignored during master election; the default value is
+As part of the ping process a master of the cluster is either elected or joined
+to. This is done automatically. The `discovery.zen.ping_timeout` (which defaults
+to `3s`) determines how long the node will wait before deciding on starting an
+election or joining an existing cluster.  Three pings will be sent over this
+timeout interval. In case where no decision can be reached after the timeout,
+the pinging process restarts.  In slow or congested networks, three seconds
+might not be enough for a node to become aware of the other nodes in its
+environment before making an election decision.  Increasing the timeout should
+be done with care in that case, as it will slow down the election process.  Once
+a node decides to join an existing formed cluster, it will send a join request
+to the master (`discovery.zen.join_timeout`) with a timeout defaulting at 20
+times the ping timeout.
+
+When the master node stops or has encountered a problem, the cluster nodes start
+pinging again and will elect a new master. This pinging round also serves as a
+protection against (partial) network failures where a node may unjustly think
+that the master has failed. In this case the node will simply hear from other
+nodes about the currently active master.
+
+If `discovery.zen.master_election.ignore_non_master_pings` is `true`, pings from
+nodes that are not master eligible (nodes where `node.master` is `false`) are
+ignored during master election; the default value is `false`.
+
+Nodes can be excluded from becoming a master by setting `node.master` to
 `false`.
 
-Nodes can be excluded from becoming a master by setting `node.master` to `false`.
-
-The `discovery.zen.minimum_master_nodes` sets the minimum
-number of master eligible nodes that need to join a newly elected master in order for an election to
-complete and for the elected node to accept its mastership. The same setting controls the minimum number of
-active master eligible nodes that should be a part of any active cluster. If this requirement is not met the
-active master node will step down and a new master election will begin.
+The `discovery.zen.minimum_master_nodes` sets the minimum number of master
+eligible nodes that need to join a newly elected master in order for an election
+to complete and for the elected node to accept its mastership. The same setting
+controls the minimum number of active master eligible nodes that should be a
+part of any active cluster. If this requirement is not met the active master
+node will step down and a new master election will begin.
 
 This setting must be set to a <<minimum_master_nodes,quorum>> of your master
 eligible nodes. It is recommended to avoid having only two master eligible
-nodes, since a quorum of two is two. Therefore, a loss of either master
-eligible node will result in an inoperable cluster.
+nodes, since a quorum of two is two. Therefore, a loss of either master eligible
+node will result in an inoperable cluster.
 
 [float]
 [[fault-detection]]
 ==== Fault Detection
 
-There are two fault detection processes running. The first is by the
-master, to ping all the other nodes in the cluster and verify that they
-are alive. And on the other end, each node pings to master to verify if
-its still alive or an election process needs to be initiated.
+There are two fault detection processes running. The first is by the master, to
+ping all the other nodes in the cluster and verify that they are alive. And on
+the other end, each node pings to master to verify if its still alive or an
+election process needs to be initiated.
 
 The following settings control the fault detection process using the
 `discovery.zen.fd` prefix:
@@ -116,19 +188,21 @@ considered failed. Defaults to `3`.
 
 The master node is the only node in a cluster that can make changes to the
 cluster state. The master node processes one cluster state update at a time,
-applies the required changes and publishes the updated cluster state to all
-the other nodes in the cluster. Each node receives the publish message, acknowledges
-it, but does *not* yet apply it. If the master does not receive acknowledgement from
-at least `discovery.zen.minimum_master_nodes` nodes within a certain time (controlled by
-the `discovery.zen.commit_timeout` setting and defaults to 30 seconds) the cluster state
-change is rejected.
-
-Once enough nodes have responded, the cluster state is committed and a message will
-be sent to all the nodes. The nodes then proceed to apply the new cluster state to their
-internal state. The master node waits for all nodes to respond, up to a timeout, before
-going ahead processing the next updates in the queue. The `discovery.zen.publish_timeout` is
-set by default to 30 seconds and is measured from the moment the publishing started. Both
-timeout settings can be changed dynamically through the <<cluster-update-settings,cluster update settings api>>
+applies the required changes and publishes the updated cluster state to all the
+other nodes in the cluster. Each node receives the publish message, acknowledges
+it, but does *not* yet apply it. If the master does not receive acknowledgement
+from at least `discovery.zen.minimum_master_nodes` nodes within a certain time
+(controlled by the `discovery.zen.commit_timeout` setting and defaults to 30
+seconds) the cluster state change is rejected.
+
+Once enough nodes have responded, the cluster state is committed and a message
+will be sent to all the nodes. The nodes then proceed to apply the new cluster
+state to their internal state. The master node waits for all nodes to respond,
+up to a timeout, before going ahead processing the next updates in the queue.
+The `discovery.zen.publish_timeout` is set by default to 30 seconds and is
+measured from the moment the publishing started. Both timeout settings can be
+changed dynamically through the <<cluster-update-settings,cluster update
+settings api>>
 
 [float]
 [[no-master-block]]
@@ -143,10 +217,14 @@ rejected when there is no active master.
 The `discovery.zen.no_master_block` setting has two valid options:
 
 [horizontal]
-`all`:: All operations on the node--i.e. both read & writes--will be rejected. This also applies for api cluster state
-read or write operations, like the get index settings, put mapping and cluster state api.
-`write`:: (default) Write operations will be rejected. Read operations will succeed, based on the last known cluster configuration.
-This may result in partial reads of stale data as this node may be isolated from the rest of the cluster.
-
-The `discovery.zen.no_master_block` setting doesn't apply to nodes-based apis (for example cluster stats, node info and
-node stats apis).  Requests to these apis will not be blocked and can run on any available node.
+`all`:: All operations on the node--i.e. both read & writes--will be rejected.
+This also applies for api cluster state read or write operations, like the get
+index settings, put mapping and cluster state api.
+`write`:: (default) Write operations will be rejected. Read operations will
+succeed, based on the last known cluster configuration.  This may result in
+partial reads of stale data as this node may be isolated from the rest of the
+cluster.
+
+The `discovery.zen.no_master_block` setting doesn't apply to nodes-based apis
+(for example cluster stats, node info and node stats apis).  Requests to these
+apis will not be blocked and can run on any available node.

plugins/discovery-file/src/main/java/org/elasticsearch/discovery/file/FileBasedDiscoveryPlugin.java

@@ -19,39 +19,33 @@
 
 package org.elasticsearch.discovery.file;
 
+import org.elasticsearch.common.logging.DeprecationLogger;
+import org.elasticsearch.common.logging.Loggers;
 import org.elasticsearch.common.network.NetworkService;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.discovery.zen.UnicastHostsProvider;
-import org.elasticsearch.env.Environment;
 import org.elasticsearch.plugins.DiscoveryPlugin;
 import org.elasticsearch.plugins.Plugin;
 import org.elasticsearch.transport.TransportService;
 
-import java.nio.file.Path;
 import java.util.Collections;
 import java.util.Map;
 import java.util.function.Supplier;
 
-/**
- * Plugin for providing file-based unicast hosts discovery. The list of unicast hosts
- * is obtained by reading the {@link FileBasedUnicastHostsProvider#UNICAST_HOSTS_FILE} in
- * the {@link Environment#configFile()}/discovery-file directory.
- */
 public class FileBasedDiscoveryPlugin extends Plugin implements DiscoveryPlugin {
 
-    private final Settings settings;
-    private final Path configPath;
+    private final DeprecationLogger deprecationLogger;
+    static final String DEPRECATION_MESSAGE
+        = "File-based discovery is now built into Elasticsearch and does not require the discovery-file plugin";
 
-    public FileBasedDiscoveryPlugin(Settings settings, Path configPath) {
-        this.settings = settings;
-        this.configPath = configPath;
+    public FileBasedDiscoveryPlugin(Settings settings) {
+        deprecationLogger = new DeprecationLogger(Loggers.getLogger(this.getClass(), settings));
     }
 
     @Override
     public Map<String, Supplier<UnicastHostsProvider>> getZenHostsProviders(TransportService transportService,
                                                                             NetworkService networkService) {
-        return Collections.singletonMap(
-            "file",
-            () -> new FileBasedUnicastHostsProvider(new Environment(settings, configPath)));
+        deprecationLogger.deprecated(DEPRECATION_MESSAGE);
+        return Collections.emptyMap();
     }
 }

plugins/discovery-file/src/main/java/org/elasticsearch/discovery/file/FileBasedUnicastHostsProvider.java

@@ -1,83 +0,0 @@
-/*
- * Licensed to Elasticsearch under one or more contributor
- * license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright
- * ownership. Elasticsearch licenses this file to you under
- * the Apache License, Version 2.0 (the "License"); you may
- * not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-
-package org.elasticsearch.discovery.file;
-
-import org.apache.logging.log4j.message.ParameterizedMessage;
-import org.apache.logging.log4j.util.Supplier;
-import org.elasticsearch.common.component.AbstractComponent;
-import org.elasticsearch.common.transport.TransportAddress;
-import org.elasticsearch.discovery.zen.UnicastHostsProvider;
-import org.elasticsearch.env.Environment;
-
-import java.io.FileNotFoundException;
-import java.io.IOException;
-import java.nio.file.Files;
-import java.nio.file.NoSuchFileException;
-import java.nio.file.Path;
-import java.util.Collections;
-import java.util.List;
-import java.util.stream.Collectors;
-import java.util.stream.Stream;
-
-/**
- * An implementation of {@link UnicastHostsProvider} that reads hosts/ports
- * from {@link #UNICAST_HOSTS_FILE}.
- *
- * Each unicast host/port that is part of the discovery process must be listed on
- * a separate line.  If the port is left off an entry, a default port of 9300 is
- * assumed.  An example unicast hosts file could read:
- *
- * 67.81.244.10
- * 67.81.244.11:9305
- * 67.81.244.15:9400
- */
-class FileBasedUnicastHostsProvider extends AbstractComponent implements UnicastHostsProvider {
-
-    static final String UNICAST_HOSTS_FILE = "unicast_hosts.txt";
-
-    private final Path unicastHostsFilePath;
-
-    FileBasedUnicastHostsProvider(Environment environment) {
-        super(environment.settings());
-        this.unicastHostsFilePath = environment.configFile().resolve("discovery-file").resolve(UNICAST_HOSTS_FILE);
-    }
-
-    @Override
-    public List<TransportAddress> buildDynamicHosts(HostsResolver hostsResolver) {
-        List<String> hostsList;
-        try (Stream<String> lines = Files.lines(unicastHostsFilePath)) {
-            hostsList = lines.filter(line -> line.startsWith("#") == false) // lines starting with `#` are comments
-                             .collect(Collectors.toList());
-        } catch (FileNotFoundException | NoSuchFileException e) {
-            logger.warn((Supplier<?>) () -> new ParameterizedMessage("[discovery-file] Failed to find unicast hosts file [{}]",
-                                                                        unicastHostsFilePath), e);
-            hostsList = Collections.emptyList();
-        } catch (IOException e) {
-            logger.warn((Supplier<?>) () -> new ParameterizedMessage("[discovery-file] Error reading unicast hosts file [{}]",
-                                                                        unicastHostsFilePath), e);
-            hostsList = Collections.emptyList();
-        }
-
-        final List<TransportAddress> dynamicHosts = hostsResolver.resolveHosts(hostsList, 1);
-        logger.debug("[discovery-file] Using dynamic discovery nodes {}", dynamicHosts);
-        return dynamicHosts;
-    }
-
-}

plugins/discovery-file/src/test/java/org/elasticsearch/discovery/file/FileBasedDiscoveryPluginDeprecationTests.java

@@ -0,0 +1,32 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.discovery.file;
+
+import org.elasticsearch.common.settings.Settings;
+import org.elasticsearch.test.ESTestCase;
+
+import static org.elasticsearch.discovery.file.FileBasedDiscoveryPlugin.DEPRECATION_MESSAGE;
+
+public class FileBasedDiscoveryPluginDeprecationTests extends ESTestCase {
+    public void testDeprecationWarning() {
+        new FileBasedDiscoveryPlugin(Settings.EMPTY).getZenHostsProviders(null, null);
+        assertWarnings(DEPRECATION_MESSAGE);
+    }
+}

server/src/main/java/org/elasticsearch/discovery/DiscoveryModule.java

@@ -33,6 +33,7 @@ import org.elasticsearch.common.settings.Setting.Property;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.transport.TransportAddress;
 import org.elasticsearch.discovery.single.SingleNodeDiscovery;
+import org.elasticsearch.discovery.zen.FileBasedUnicastHostsProvider;
 import org.elasticsearch.discovery.zen.SettingsBasedHostsProvider;
 import org.elasticsearch.discovery.zen.UnicastHostsProvider;
 import org.elasticsearch.discovery.zen.ZenDiscovery;
@@ -40,6 +41,7 @@ import org.elasticsearch.plugins.DiscoveryPlugin;
 import org.elasticsearch.threadpool.ThreadPool;
 import org.elasticsearch.transport.TransportService;
 
+import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
@@ -69,10 +71,11 @@ public class DiscoveryModule {
     public DiscoveryModule(Settings settings, ThreadPool threadPool, TransportService transportService,
                            NamedWriteableRegistry namedWriteableRegistry, NetworkService networkService, MasterService masterService,
                            ClusterApplier clusterApplier, ClusterSettings clusterSettings, List<DiscoveryPlugin> plugins,
-                           AllocationService allocationService) {
+                           AllocationService allocationService, Path configFile) {
         final Collection<BiConsumer<DiscoveryNode,ClusterState>> joinValidators = new ArrayList<>();
         final Map<String, Supplier<UnicastHostsProvider>> hostProviders = new HashMap<>();
         hostProviders.put("settings", () -> new SettingsBasedHostsProvider(settings, transportService));
+        hostProviders.put("file", () -> new FileBasedUnicastHostsProvider(settings, configFile));
         for (DiscoveryPlugin plugin : plugins) {
             plugin.getZenHostsProviders(transportService, networkService).entrySet().forEach(entry -> {
                 if (hostProviders.put(entry.getKey(), entry.getValue()) != null) {

server/src/main/java/org/elasticsearch/discovery/zen/FileBasedUnicastHostsProvider.java

@@ -0,0 +1,92 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.discovery.zen;
+
+import org.apache.logging.log4j.message.ParameterizedMessage;
+import org.elasticsearch.common.component.AbstractComponent;
+import org.elasticsearch.common.settings.Settings;
+import org.elasticsearch.common.transport.TransportAddress;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+/**
+ * An implementation of {@link UnicastHostsProvider} that reads hosts/ports
+ * from {@link #UNICAST_HOSTS_FILE}.
+ *
+ * Each unicast host/port that is part of the discovery process must be listed on
+ * a separate line.  If the port is left off an entry, a default port of 9300 is
+ * assumed.  An example unicast hosts file could read:
+ *
+ * 67.81.244.10
+ * 67.81.244.11:9305
+ * 67.81.244.15:9400
+ */
+public class FileBasedUnicastHostsProvider extends AbstractComponent implements UnicastHostsProvider {
+
+    public static final String UNICAST_HOSTS_FILE = "unicast_hosts.txt";
+
+    private final Path unicastHostsFilePath;
+    private final Path legacyUnicastHostsFilePath;
+
+    public FileBasedUnicastHostsProvider(Settings settings, Path configFile) {
+        super(settings);
+        this.unicastHostsFilePath = configFile.resolve(UNICAST_HOSTS_FILE);
+        this.legacyUnicastHostsFilePath = configFile.resolve("discovery-file").resolve(UNICAST_HOSTS_FILE);
+    }
+
+    private List<String> getHostsList() {
+        if (Files.exists(unicastHostsFilePath)) {
+            return readFileContents(unicastHostsFilePath);
+        }
+
+        if (Files.exists(legacyUnicastHostsFilePath)) {
+            deprecationLogger.deprecated("Found dynamic hosts list at [{}] but this path is deprecated. This list should be at [{}] " +
+                "instead. Support for the deprecated path will be removed in future.", legacyUnicastHostsFilePath, unicastHostsFilePath);
+            return readFileContents(legacyUnicastHostsFilePath);
+        }
+
+        logger.warn("expected, but did not find, a dynamic hosts list at [{}]", unicastHostsFilePath);
+
+        return Collections.emptyList();
+    }
+
+    private List<String> readFileContents(Path path) {
+        try (Stream<String> lines = Files.lines(path)) {
+            return lines.filter(line -> line.startsWith("#") == false) // lines starting with `#` are comments
+                .collect(Collectors.toList());
+        } catch (IOException e) {
+            logger.warn(() -> new ParameterizedMessage("failed to read file [{}]", unicastHostsFilePath), e);
+            return Collections.emptyList();
+        }
+    }
+
+    @Override
+    public List<TransportAddress> buildDynamicHosts(HostsResolver hostsResolver) {
+        final List<TransportAddress> transportAddresses = hostsResolver.resolveHosts(getHostsList(), 1);
+        logger.debug("seed addresses: {}", transportAddresses);
+        return transportAddresses;
+    }
+}

server/src/main/java/org/elasticsearch/node/Node.java

@@ -471,7 +471,7 @@ public class Node implements Closeable {
             final DiscoveryModule discoveryModule = new DiscoveryModule(this.settings, threadPool, transportService, namedWriteableRegistry,
                 networkService, clusterService.getMasterService(), clusterService.getClusterApplierService(),
                 clusterService.getClusterSettings(), pluginsService.filterPlugins(DiscoveryPlugin.class),
-                clusterModule.getAllocationService());
+                clusterModule.getAllocationService(), environment.configFile());
             this.nodeService = new NodeService(settings, threadPool, monitorService, discoveryModule.getDiscovery(),
                 transportService, indicesService, pluginsService, circuitBreakerService, scriptModule.getScriptService(),
                 httpServerTransport, ingestService, clusterService, settingsModule.getSettingsFilter(), responseCollectorService,

server/src/test/java/org/elasticsearch/discovery/DiscoveryModuleTests.java

@@ -18,7 +18,6 @@
  */
 package org.elasticsearch.discovery;
 
-import org.elasticsearch.core.internal.io.IOUtils;
 import org.elasticsearch.Version;
 import org.elasticsearch.cluster.ClusterState;
 import org.elasticsearch.cluster.node.DiscoveryNode;
@@ -29,6 +28,7 @@ import org.elasticsearch.common.io.stream.NamedWriteableRegistry;
 import org.elasticsearch.common.network.NetworkService;
 import org.elasticsearch.common.settings.ClusterSettings;
 import org.elasticsearch.common.settings.Settings;
+import org.elasticsearch.core.internal.io.IOUtils;
 import org.elasticsearch.discovery.zen.UnicastHostsProvider;
 import org.elasticsearch.discovery.zen.ZenDiscovery;
 import org.elasticsearch.plugins.DiscoveryPlugin;
@@ -99,7 +99,7 @@ public class DiscoveryModuleTests extends ESTestCase {
 
     private DiscoveryModule newModule(Settings settings, List<DiscoveryPlugin> plugins) {
         return new DiscoveryModule(settings, threadPool, transportService, namedWriteableRegistry, null, masterService,
-            clusterApplier, clusterSettings, plugins, null);
+            clusterApplier, clusterSettings, plugins, null, createTempDir().toAbsolutePath());
     }
 
     public void testDefaults() {

plugins/discovery-file/src/test/java/org/elasticsearch/discovery/file/FileBasedUnicastHostsProviderTests.java → server/src/test/java/org/elasticsearch/discovery/zen/FileBasedUnicastHostsProviderTests.java

@@ -17,7 +17,7 @@
  * under the License.
  */
 
-package org.elasticsearch.discovery.file;
+package org.elasticsearch.discovery.zen;
 
 import org.elasticsearch.common.io.stream.NamedWriteableRegistry;
 import org.elasticsearch.common.network.NetworkService;
@@ -26,9 +26,7 @@ import org.elasticsearch.common.transport.BoundTransportAddress;
 import org.elasticsearch.common.transport.TransportAddress;
 import org.elasticsearch.common.unit.TimeValue;
 import org.elasticsearch.common.util.BigArrays;
-import org.elasticsearch.discovery.zen.UnicastZenPing;
 import org.elasticsearch.env.Environment;
-import org.elasticsearch.env.TestEnvironment;
 import org.elasticsearch.indices.breaker.NoneCircuitBreakerService;
 import org.elasticsearch.test.ESTestCase;
 import org.elasticsearch.test.transport.MockTransportService;
@@ -50,16 +48,15 @@ import java.util.List;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
 
-import static org.elasticsearch.discovery.file.FileBasedUnicastHostsProvider.UNICAST_HOSTS_FILE;
+import static org.elasticsearch.discovery.zen.FileBasedUnicastHostsProvider.UNICAST_HOSTS_FILE;
 
-/**
- * Tests for {@link FileBasedUnicastHostsProvider}.
- */
 public class FileBasedUnicastHostsProviderTests extends ESTestCase {
 
+    private boolean legacyLocation;
     private ThreadPool threadPool;
     private ExecutorService executorService;
     private MockTransportService transportService;
+    private Path configPath;
 
     @Before
     public void setUp() throws Exception {
@@ -83,23 +80,20 @@ public class FileBasedUnicastHostsProviderTests extends ESTestCase {
 
     @Before
     public void createTransportSvc() {
-        MockTcpTransport transport =
-            new MockTcpTransport(Settings.EMPTY,
-                                    threadPool,
-                                    BigArrays.NON_RECYCLING_INSTANCE,
-                                    new NoneCircuitBreakerService(),
-                                    new NamedWriteableRegistry(Collections.emptyList()),
-                                    new NetworkService(Collections.emptyList())) {
-                @Override
-                public BoundTransportAddress boundAddress() {
-                    return new BoundTransportAddress(
-                        new TransportAddress[]{new TransportAddress(InetAddress.getLoopbackAddress(), 9300)},
-                        new TransportAddress(InetAddress.getLoopbackAddress(), 9300)
-                    );
-                }
-            };
+        final MockTcpTransport transport = new MockTcpTransport(Settings.EMPTY, threadPool, BigArrays.NON_RECYCLING_INSTANCE,
+            new NoneCircuitBreakerService(),
+            new NamedWriteableRegistry(Collections.emptyList()),
+            new NetworkService(Collections.emptyList())) {
+            @Override
+            public BoundTransportAddress boundAddress() {
+                return new BoundTransportAddress(
+                    new TransportAddress[]{new TransportAddress(InetAddress.getLoopbackAddress(), 9300)},
+                    new TransportAddress(InetAddress.getLoopbackAddress(), 9300)
+                );
+            }
+        };
         transportService = new MockTransportService(Settings.EMPTY, transport, threadPool, TransportService.NOOP_TRANSPORT_INTERCEPTOR,
-                null);
+            null);
     }
 
     public void testBuildDynamicNodes() throws Exception {
@@ -114,18 +108,27 @@ public class FileBasedUnicastHostsProviderTests extends ESTestCase {
         assertEquals(9300, nodes.get(2).getPort());
     }
 
+    public void testBuildDynamicNodesLegacyLocation() throws Exception {
+        legacyLocation = true;
+        testBuildDynamicNodes();
+        assertDeprecatedLocationWarning();
+    }
+
     public void testEmptyUnicastHostsFile() throws Exception {
         final List<String> hostEntries = Collections.emptyList();
         final List<TransportAddress> addresses = setupAndRunHostProvider(hostEntries);
         assertEquals(0, addresses.size());
     }
 
-    public void testUnicastHostsDoesNotExist() throws Exception {
-        final Settings settings = Settings.builder()
-                                      .put(Environment.PATH_HOME_SETTING.getKey(), createTempDir())
-                                      .build();
-        final Environment environment = TestEnvironment.newEnvironment(settings);
-        final FileBasedUnicastHostsProvider provider = new FileBasedUnicastHostsProvider(environment);
+    public void testEmptyUnicastHostsFileLegacyLocation() throws Exception {
+        legacyLocation = true;
+        testEmptyUnicastHostsFile();
+        assertDeprecatedLocationWarning();
+    }
+
+    public void testUnicastHostsDoesNotExist() {
+        final Settings settings = Settings.builder().put(Environment.PATH_HOME_SETTING.getKey(), createTempDir()).build();
+        final FileBasedUnicastHostsProvider provider = new FileBasedUnicastHostsProvider(settings, createTempDir().toAbsolutePath());
         final List<TransportAddress> addresses = provider.buildDynamicHosts((hosts, limitPortCounts) ->
             UnicastZenPing.resolveHostsLists(executorService, logger, hosts, limitPortCounts, transportService,
                 TimeValue.timeValueSeconds(10)));
@@ -133,42 +136,60 @@ public class FileBasedUnicastHostsProviderTests extends ESTestCase {
     }
 
     public void testInvalidHostEntries() throws Exception {
-        List<String> hostEntries = Arrays.asList("192.168.0.1:9300:9300");
-        List<TransportAddress> addresses = setupAndRunHostProvider(hostEntries);
+        final List<String> hostEntries = Arrays.asList("192.168.0.1:9300:9300");
+        final List<TransportAddress> addresses = setupAndRunHostProvider(hostEntries);
         assertEquals(0, addresses.size());
     }
 
+    public void testInvalidHostEntriesLegacyLocation() throws Exception {
+        legacyLocation = true;
+        testInvalidHostEntries();
+        assertDeprecatedLocationWarning();
+    }
+
     public void testSomeInvalidHostEntries() throws Exception {
-        List<String> hostEntries = Arrays.asList("192.168.0.1:9300:9300", "192.168.0.1:9301");
-        List<TransportAddress> addresses = setupAndRunHostProvider(hostEntries);
+        final List<String> hostEntries = Arrays.asList("192.168.0.1:9300:9300", "192.168.0.1:9301");
+        final List<TransportAddress> addresses = setupAndRunHostProvider(hostEntries);
         assertEquals(1, addresses.size()); // only one of the two is valid and will be used
         assertEquals("192.168.0.1", addresses.get(0).getAddress());
         assertEquals(9301, addresses.get(0).getPort());
     }
 
+    public void testSomeInvalidHostEntriesLegacyLocation() throws Exception {
+        legacyLocation = true;
+        testSomeInvalidHostEntries();
+        assertDeprecatedLocationWarning();
+    }
+
     // sets up the config dir, writes to the unicast hosts file in the config dir,
     // and then runs the file-based unicast host provider to get the list of discovery nodes
     private List<TransportAddress> setupAndRunHostProvider(final List<String> hostEntries) throws IOException {
         final Path homeDir = createTempDir();
         final Settings settings = Settings.builder()
-                                      .put(Environment.PATH_HOME_SETTING.getKey(), homeDir)
-                                      .build();
-        final Path configPath;
+            .put(Environment.PATH_HOME_SETTING.getKey(), homeDir)
+            .build();
         if (randomBoolean()) {
             configPath = homeDir.resolve("config");
         } else {
             configPath = createTempDir();
         }
-        final Path discoveryFilePath = configPath.resolve("discovery-file");
+        final Path discoveryFilePath = legacyLocation ? configPath.resolve("discovery-file") : configPath;
         Files.createDirectories(discoveryFilePath);
         final Path unicastHostsPath = discoveryFilePath.resolve(UNICAST_HOSTS_FILE);
         try (BufferedWriter writer = Files.newBufferedWriter(unicastHostsPath)) {
             writer.write(String.join("\n", hostEntries));
         }
 
-        return new FileBasedUnicastHostsProvider(
-                new Environment(settings, configPath)).buildDynamicHosts((hosts, limitPortCounts) ->
-                    UnicastZenPing.resolveHostsLists(executorService, logger, hosts, limitPortCounts, transportService,
-                        TimeValue.timeValueSeconds(10)));
+        return new FileBasedUnicastHostsProvider(settings, configPath).buildDynamicHosts((hosts, limitPortCounts) ->
+            UnicastZenPing.resolveHostsLists(executorService, logger, hosts, limitPortCounts, transportService,
+                TimeValue.timeValueSeconds(10)));
+    }
+
+    private void assertDeprecatedLocationWarning() {
+        assertWarnings("Found dynamic hosts list at [" +
+            configPath.resolve("discovery-file").resolve(UNICAST_HOSTS_FILE) +
+            "] but this path is deprecated. This list should be at [" +
+            configPath.resolve(UNICAST_HOSTS_FILE) +
+            "] instead. Support for the deprecated path will be removed in future.");
     }
 }