Docs: Document the most important changes to zen discovery.

Closes #7746

docs/reference/migration/migrate_1_x.asciidoc

@@ -71,4 +71,12 @@ curl -XGET 'http://localhost:9200/_all/_mappings'
 curl -XGET 'http://localhost:9200/_mappings'
 --------------------------------------------------
 
+==== Zen discovery
 
+Each cluster must have an elected master node in order to be fully operational. Once a node loses its elected master
+node it will reject some or all operations.
+
+On versions before `1.4.0.Beta1` all operations are rejected when a node loses its elected master. From `1.4.0.Beta1`
+only write operations will be rejected by default. Read operations will still be served based on the information available
+to the node, which may result in being partial and possibly also stale. If the default is undesired then the
+pre `1.4.0.Beta1` behaviour can be enabled, see: <<modules-discovery-zen,no-master-block>>

docs/reference/modules/discovery/zen.asciidoc

@@ -68,22 +68,30 @@ perform the discovery.
 [[master-election]]
 ==== Master Election
 
-As part of the initial ping process a master of the cluster is either
+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`) allows for the
 tweaking of election time to handle cases of slow or congested networks
 (higher values assure less chance of failure). Once a node joins, 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 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.
+
 Nodes can be excluded from becoming a master by setting `node.master` to
 `false`. Note, once a node is a client node (`node.client` set to
 `true`), it will not be allowed to become a master (`node.master` is
 automatically set to `false`).
 
 The `discovery.zen.minimum_master_nodes` sets the minimum
-number of master eligible nodes a node should "see" in order to operate
-within the cluster. Its recommended to set it to a higher value than 1
-when running more than 2 nodes in the cluster.
+number of master eligible nodes a node should "see" in order to win a master election.
+It must be set to a 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 node will result in an inoperable cluster
 
 [float]
 [[fault-detection]]
@@ -160,3 +168,21 @@ 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 can be changed dynamically through the
 <<cluster-update-settings,cluster update settings api>>
+
+[float]
+[[no-master-block]]
+==== No master block
+
+coming[1.4.0.Beta1]
+
+For a node to be fully operational, it must have an active master. The `discovery.zen.no_master_block` settings controls
+what operations should be rejected when there is no active master.
+
+The `discovery.zen.no_master_block` setting has two valid options:
+* `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` - Write operations will be rejected. Read operations will succeed, based on the last known cluster configuration.
+This may result in partial reads or stale data as this node may be isolated from the rest of the cluster. This is the default.
+
+The `discovery.zen.no_master_block` setting doesn't apply for nodes based apis (for example cluster stats, node info and
+node stats apis) which will not be blocked and try to execute on any node possible.