website: Documenting DNS settings

website/source/docs/agent/dns.html.markdown

@@ -19,7 +19,7 @@ with no failing health checks. It's that simple!
 
 There are a number of [configuration options](/docs/agent/options.html) that
 are important for the DNS interface. They are `client_addr`, `ports.dns`, `recursor`,
-and `domain`. By default Consul will listen on 127.0.0.1:8600 for DNS queries
+`domain`, and `dns_config`. By default Consul will listen on 127.0.0.1:8600 for DNS queries
 in the "consul." domain, without support for DNS recursion.
 
 There are a few ways to use the DNS interface. One option is to use a custom
@@ -118,3 +118,10 @@ without setting the truncate bit. This is to prevent a redundant lookup over
 TCP which generate additional load. If the lookup is done over TCP, the results
 are not truncated.
 
+## Caching
+
+By default, all DNS results served by Consul set a 0 TTL value. This disables
+caching of DNS results. However, there are many situations in which caching is
+desirable for performance and scalability. This is discussed more in the guide
+for [DNS Caching](/docs/guides/dns-cache.html).
+

website/source/docs/agent/options.html.markdown

@@ -183,6 +183,30 @@ definitions support being updated during a reload.
   This flag can be used to change that domain. All queries in this domain are assumed
   to be handled by Consul, and will not be recursively resolved.
 
+* `dns_config` - This object allows a number of sub-keys to be set which can tune
+  how DNS queries are perfomed. See this guide on [DNS caching](/docs/guides/dns-cache.html).
+  The following sub-keys are available:
+
+  * `node_ttl` - By default, this is "0s", which means all node lookups are served with
+  a 0 TTL value. This can be set to allow node lookups to set a TTL value, which enables
+  DNS caching. This should be specified with the "s" suffix for second, or "m" for minute.
+
+  * `service_ttl` - This is a sub-object, which allows for setting a TTL on service lookups
+  with a per-service policy. The "*" wildcard service can be specified and is used when
+  there is no specific policy available for a service. By default, all services are served
+  with a 0 TTL value. Setting this enables DNS caching.
+
+  * `allow_stale` - Enables a stale query for DNS information. This allows any Consul
+  server to service the request, instead of only the leader. The advantage of this is
+  you get linear read scalability with Consul servers. By default, this is false, meaning
+  all requests are serviced by the leader. This provides stronger consistency but
+  with less throughput and higher latency.
+
+  * `max_stale` - When `allow_stale` is specified, this is used to limit how
+  stale of a result will be used. By default, this is set to "5s", which means
+  if a Consul server is more than 5 seconds behind the leader, the query will be
+  re-evaluated on the leader to get more up-to-date results.
+
 * `enable_debug` - When set, enables some additional debugging features. Currently,
   only used to set the runtime profiling HTTP endpoints.
 
@@ -201,12 +225,12 @@ definitions support being updated during a reload.
 
 * `ports` - This is a nested object that allows setting the bind ports
    for the following keys:
-    * dns - The DNS server, -1 to disable. Default 8600.
+    * `dns` - The DNS server, -1 to disable. Default 8600.
-    * http - The HTTP api, -1 to disable. Default 8500.
+    * `http` - The HTTP api, -1 to disable. Default 8500.
-    * rpc - The RPC endpoint. Default 8400.
+    * `rpc` - The RPC endpoint. Default 8400.
-    * serf_lan - The Serf LAN port. Default 8301.
+    * `serf_lan` - The Serf LAN port. Default 8301.
-    * serf_wan - The Serf WAN port. Default 8302.
+    * `serf_wan` - The Serf WAN port. Default 8302.
-    * server - Server RPC address. Default 8300.
+    * `server` - Server RPC address. Default 8300.
 
 * `recursor` - This flag provides an address of an upstream DNS server that is used to
   recursively resolve queries if they are not inside the service domain for consul. For example,

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

@@ -0,0 +1,74 @@
+---
+layout: "docs"
+page_title: "DNS Caching"
+sidebar_current: "docs-guides-dns-cache"
+---
+
+# DNS Caching
+
+One of the main interfaces to Consul is DNS. Using DNS is a simple way
+integrate Consul into an existing infrastructure without any high-touch
+integration.
+
+By default, Consul serves all DNS results with a 0 TTL value. This prevents
+any caching. The advantage of this is that each DNS lookup is always re-evaluated
+and the most timely information is served. However this adds a latency hit
+for each lookup and can potentially exhaust the query throughput of a cluster.
+
+For this reason, Consul provides a number of tuning parameters that can
+be used to 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 potentially
+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
+are `dns_config.allow_stale` which must be set to enable stale reads,
+and `dns_config.max_stale` which limits how stale results are allowed to
+be.
+
+By default, `allow_stale` is disabled meaning no stale results may be served.
+The default for `max_stale` is 5 seconds. This means that is `allow_stale` is
+enabled, we will use data from any Consul server that is within 5 seconds
+of the leader.
+
+## TTL Values
+
+TTL values can be set to allow DNS results to be cached upstream
+of Consul which can be reduce the number of lookups and to amortize
+the latency of doing a DNS lookup. By default, all TTLs are zero,
+preventing any caching.
+
+To enable caching of node lookups (e.g. "foo.node.consul"), we can set
+the `dns_config.node_ttl` value. This can be set to "10s" for example,
+and all node lookups will serve results with a 10 second TTL.
+
+Service TTLs can be specified at a more fine grain level. You can set
+a TTL on a per-service level, and additionally a wildcard can be specified
+that matches if there is no specific service TTL provided.
+
+This is specified using the `dns_config.service_ttl` map. The "*" service
+is the wildcard service. For example, if we specify:
+
+```
+    {
+        "dns_config": {
+            "service_ttl": {
+                "*": "5s",
+                "web": "30s"
+            }
+        }
+    }
+```
+
+This sets all lookups to "web.service.consul" to use a 30 second TTL,
+while lookups to "db.service.consul" or "api.service.consul" will use the
+5 second TTL from the wildcard.
+

website/source/layouts/docs.erb

@@ -136,6 +136,10 @@
 					<a href="/docs/guides/bootstrapping.html">Bootstrapping</a>
                     </li>
 
+					<li<%= sidebar_current("docs-guides-dns-cache") %>>
+					<a href="/docs/guides/dns-cache.html">DNS Caching</a>
+					</li>
+
 					<li<%= sidebar_current("docs-guides-forwarding") %>>
 					<a href="/docs/guides/forwarding.html">DNS Forwarding</a>
 					</li>