⤵️ Merge from `master`; no conflicts

CHANGELOG.md

@@ -2,8 +2,9 @@
 
 IMPROVEMENTS:
 
-* agent: Blocking queries on service-specific health and catalog endpoints now return a per-service `X-Consul-Index` improving watch performance on very busy clusters. [[GH-3890](https://github.com/hashicorp/consul/issues/3890)]
+* agent: Blocking queries on service-specific health and catalog endpoints now return a per-service `X-Consul-Index` improving watch performance on very busy clusters. [[GH-3890](https://github.com/hashicorp/consul/issues/3890)]. **Note this may break blocking clients that relied on undocumented implementation details** as noted in the [upgrade docs](https://github.com/hashicorp/consul/blob/master/website/source/docs/upgrading.html.md#upgrade-from-version-106-to-higher).
 * dns: Introduced a new config param to limit the number of A/AAAA records returned. [[GH-3940](https://github.com/hashicorp/consul/issues/3940)]
+
 BUG FIXES:
 
 * agent: Fixed an issue where the coordinate update endpoint was not correctly parsing the ACL token. [[GH-3892](https://github.com/hashicorp/consul/issues/3892)]

website/source/docs/commands/index.html.md

@@ -27,15 +27,15 @@ usage: consul [--version] [--help] <command> [<args>]
 
 Available commands are:
     agent          Runs a Consul agent
-    configtest     Validate config file
+    catalog        Interact with the catalog
     event          Fire a new event
     exec           Executes a command on Consul nodes
     force-leave    Forces a member of the cluster to enter the "left" state
-    info           Provides debugging information for operators
+    info           Provides debugging information for operators.
     join           Tell Consul agent to join cluster
     keygen         Generates a new encryption key
     keyring        Manages gossip layer encryption keys
-    kv             Interact with the KV store
+    kv             Interact with the key-value store
     leave          Gracefully leaves the Consul cluster and shuts down
     lock           Execute a command holding a lock
     maint          Controls node or service maintenance mode
@@ -44,6 +44,8 @@ Available commands are:
     operator       Provides cluster-level tools for Consul operators
     reload         Triggers the agent to reload configuration files
     rtt            Estimates network round trip time between nodes
+    snapshot       Saves, restores and inspects snapshots of Consul server state
+    validate       Validate config files/directories
     version        Prints the Consul version
     watch          Watch for changes in Consul
 ```

website/source/docs/guides/dns-cache.html.md

@@ -24,31 +24,31 @@ customize how DNS queries are handled.
 ## Stale Reads
 
 Stale reads can be used to reduce latency and increase the throughput
-of DNS queries. By default, all reads are serviced by a
-[single leader node](/docs/internals/consensus.html).
-These reads are strongly consistent but are limited by the throughput
-of a single node. Doing a stale read allows any Consul server to
-service a query, but non-leader nodes may return data that is
-out-of-date. By allowing data to be slightly stale, we get horizontal
-read scalability. Now any Consul server can service the request, so we
-increase throughput by the number of servers in a cluster.
-
-The [settings](/docs/agent/options.html) used to control stale reads
+of DNS queries. The [settings](/docs/agent/options.html) used to control stale reads
 are [`dns_config.allow_stale`](/docs/agent/options.html#allow_stale),
-which must be set to enable stale reads, and
-[`dns_config.max_stale`](/docs/agent/options.html#max_stale)
+which must be set to enable stale reads, and [`dns_config.max_stale`](/docs/agent/options.html#max_stale)
 which limits how stale results are allowed to be.
 
-Starting from Consul 0.7, [`allow_stale`](/docs/agent/options.html#allow_stale)
+Since Consul 0.7.1, [`allow_stale`](/docs/agent/options.html#allow_stale)
 is enabled by default, using a [`max_stale`](/docs/agent/options.html#max_stale)
-value that defaults to 5 seconds, meaning that we will use data from
-any Consul server that is within 5 seconds of the leader. In Consul 0.7.1, the
-default for `max_stale` was been increased from 5 seconds to a near-indefinite
-threshold (10 years) to allow DNS queries to continue to be served in the event
+value that defaults to a near-indefinite threshold (10 years) to allow DNS queries to continue to be served in the event
 of a long outage with no leader. A new telemetry counter has also been added at
 `consul.dns.stale_queries` to track when agents serve DNS queries that are stale
 by more than 5 seconds.
 
+Doing a stale read allows any Consul server to
+service a query, but non-leader nodes may return data that is
+out-of-date. By allowing data to be slightly stale, we get horizontal
+read scalability. Now any Consul server can service the request, so we
+increase throughput by the number of servers in a cluster.
+
+If you want to prevent
+stale reads or limit how stale they can be, you can set `allow_stale`
+to false or use a lower value for `max_stale`. Doing the first will ensure that
+all reads are serviced by a [single leader node](/docs/internals/consensus.html).
+The reads will then be strongly consistent but will be limited by the throughput
+of a single node. 
+
 ## Negative Response Caching
 
 Some DNS clients cache negative responses - that is, Consul returning a "not