diff --git a/website/source/docs/agent/dns.html.markdown b/website/source/docs/agent/dns.html.markdown index fe0b1fa6ea..46303a60d6 100644 --- a/website/source/docs/agent/dns.html.markdown +++ b/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). + diff --git a/website/source/docs/agent/options.html.markdown b/website/source/docs/agent/options.html.markdown index b185a1f458..bc95aea789 100644 --- a/website/source/docs/agent/options.html.markdown +++ b/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. - * http - The HTTP api, -1 to disable. Default 8500. - * rpc - The RPC endpoint. Default 8400. - * serf_lan - The Serf LAN port. Default 8301. - * serf_wan - The Serf WAN port. Default 8302. - * server - Server RPC address. Default 8300. + * `dns` - The DNS server, -1 to disable. Default 8600. + * `http` - The HTTP api, -1 to disable. Default 8500. + * `rpc` - The RPC endpoint. Default 8400. + * `serf_lan` - The Serf LAN port. Default 8301. + * `serf_wan` - The Serf WAN port. Default 8302. + * `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, diff --git a/website/source/docs/guides/dns-cache.html.markdown b/website/source/docs/guides/dns-cache.html.markdown new file mode 100644 index 0000000000..37d79fc476 --- /dev/null +++ b/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. + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 3d6c848083..7af4ba6a01 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -136,6 +136,10 @@ Bootstrapping +