[Zen2] Update documentation for Zen2

distribution/src/config/elasticsearch.yml

@@ -67,11 +67,11 @@ ${path.logs}
 #
 #discovery.zen.ping.unicast.hosts: ["host1", "host2"]
 #
-# Prevent the "split brain" by configuring the majority of nodes (total number of master-eligible nodes / 2 + 1):
+# Bootstrap the cluster using an initial set of master-eligible nodes:
 #
-#discovery.zen.minimum_master_nodes: 
+#cluster.initial_master_nodes: ["node-1", "node-2"]
 #
-# For more information, consult the zen discovery module documentation.
+# For more information, consult the discovery and cluster formation module documentation.
 #
 # ---------------------------------- Gateway -----------------------------------
 #

docs/plugins/discovery.asciidoc

@@ -1,8 +1,8 @@
 [[discovery]]
 == Discovery Plugins
 
-Discovery plugins extend Elasticsearch by adding new discovery mechanisms that
-can be used instead of {ref}/modules-discovery-zen.html[Zen Discovery].
+Discovery plugins extend Elasticsearch by adding new host providers that
+can be used to extend the {ref}/modules-discovery-zen.html[cluster formation module].
 
 [float]
 ==== Core discovery plugins
@@ -26,7 +26,6 @@ The Google Compute Engine discovery plugin uses the GCE API for unicast discover
 
 A number of discovery plugins have been contributed by our community:
 
-* https://github.com/shikhar/eskka[eskka Discovery Plugin] (by Shikhar Bhushan)
 * https://github.com/fabric8io/elasticsearch-cloud-kubernetes[Kubernetes Discovery Plugin] (by Jimmi Dyson, http://fabric8.io[fabric8])
 
 include::discovery-ec2.asciidoc[]

docs/reference/migration/migrate_7_0.asciidoc

@@ -11,6 +11,7 @@ See also <<release-highlights>> and <<es-release-notes>>.
 
 * <<breaking_70_aggregations_changes>>
 * <<breaking_70_cluster_changes>>
+* <<breaking_70_discovery_changes>>
 * <<breaking_70_indices_changes>>
 * <<breaking_70_mappings_changes>>
 * <<breaking_70_search_changes>>
@@ -44,6 +45,7 @@ Elasticsearch 6.x in order to be readable by Elasticsearch 7.x.
 include::migrate_7_0/aggregations.asciidoc[]
 include::migrate_7_0/analysis.asciidoc[]
 include::migrate_7_0/cluster.asciidoc[]
+include::migrate_7_0/discovery.asciidoc[]
 include::migrate_7_0/indices.asciidoc[]
 include::migrate_7_0/mappings.asciidoc[]
 include::migrate_7_0/search.asciidoc[]

docs/reference/migration/migrate_7_0/cluster.asciidoc

@@ -25,12 +25,3 @@ Clusters now have soft limits on the total number of open shards in the cluster
 based on the number of nodes and the `cluster.max_shards_per_node` cluster
 setting, to prevent accidental operations that would destabilize the cluster.
 More information can be found in the <<misc-cluster,documentation for that setting>>.
-
-[float]
-==== Discovery configuration is required in production
-Production deployments of Elasticsearch now require at least one of the following settings
-to be specified in the `elasticsearch.yml` configuration file:
-
-- `discovery.zen.ping.unicast.hosts`
-- `discovery.zen.hosts_provider`
-- `cluster.initial_master_nodes`

docs/reference/migration/migrate_7_0/discovery.asciidoc

@@ -0,0 +1,38 @@
+[float]
+[[breaking_70_discovery_changes]]
+=== Discovery changes
+
+[float]
+==== Cluster bootstrapping is required if discovery is configured
+
+The first time a cluster is started, `cluster.initial_master_nodes` must be set
+to perform cluster bootstrapping. It should contain the names of the
+master-eligible nodes in the initial cluster and be defined on every
+master-eligible node in the cluster. The
+<<modules-discovery-bootstrap-cluster,cluster bootstrapping reference
+documentation>> describes this setting in more detail.
+
+The `discovery.zen.minimum_master_nodes` setting is required during a rolling
+upgrade from 6.x, but can be removed in all other circumstances.
+
+[float]
+==== Removing master-eligible nodes sometimes requires voting exclusions
+
+If you wish to remove half or more of the master-eligible nodes from a cluster,
+you must first exclude the affected nodes from the voting configuration using
+the <<modules-discovery-adding-removing-nodes,voting config exclusions API>>.
+This is not required if removing fewer than half of the master-eligible nodes
+at once. This is also not required when only removing master-ineligible nodes
+such as data-only nodes or coordinating-only nodes. Finally, this is not
+required when adding nodes to the cluster, only when removing them.
+
+[float]
+==== Discovery configuration is required in production
+
+Production deployments of Elasticsearch now require at least one of the
+following settings to be specified in the `elasticsearch.yml` configuration
+file:
+
+- `discovery.zen.ping.unicast.hosts`
+- `discovery.zen.hosts_provider`
+- `cluster.initial_master_nodes`

docs/reference/modules.asciidoc

@@ -18,13 +18,13 @@ These settings can be dynamically updated on a live cluster with the
 
 The modules in this section are:
 
-<<modules-cluster,Cluster-level routing and shard allocation>>::
+<<modules-discovery,Discovery and cluster formation>>::
 
-    Settings to control where, when, and how shards are allocated to nodes.
+    How nodes discover each other, elect a master and form a cluster.
 
-<<modules-discovery,Discovery>>::
+<<modules-cluster,Shard allocation and cluster-level routing>>::
 
-    How nodes discover each other to form a cluster.
+    Settings to control where, when, and how shards are allocated to nodes.
 
 <<modules-gateway,Gateway>>::
 
@@ -85,10 +85,10 @@ The modules in this section are:
 --
 
 
-include::modules/cluster.asciidoc[]
-
 include::modules/discovery.asciidoc[]
 
+include::modules/cluster.asciidoc[]
+
 include::modules/gateway.asciidoc[]
 
 include::modules/http.asciidoc[]

docs/reference/modules/cluster.asciidoc

@@ -1,5 +1,5 @@
 [[modules-cluster]]
-== Cluster
+== Shard allocation and cluster-level routing
 
 One of the main roles of the master is to decide which shards to allocate to
 which nodes, and when to move shards between nodes in order to rebalance the