From 669b9f61f91bd1faa8cbe283dd93da0345f0a001 Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Wed, 25 Feb 2015 10:45:21 -0500 Subject: [PATCH] Website: GH-730 links and clean-up for /docs/guides/dns-cache.html --- .../docs/guides/dns-cache.html.markdown | 56 ++++++++++--------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/website/source/docs/guides/dns-cache.html.markdown b/website/source/docs/guides/dns-cache.html.markdown index 30eb716c8f..c16f275cba 100644 --- a/website/source/docs/guides/dns-cache.html.markdown +++ b/website/source/docs/guides/dns-cache.html.markdown @@ -3,61 +3,65 @@ layout: "docs" page_title: "DNS Caching" sidebar_current: "docs-guides-dns-cache" description: |- - 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. + One of the main interfaces to Consul is DNS. Using DNS is a simple way to integrate Consul into an existing infrastructure without any high-touch integration. --- # DNS Caching -One of the main interfaces to Consul is DNS. Using DNS is a simple way +One of the main interfaces to Consul is DNS. Using DNS is a simple way to 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 +any caching. The advantage is that each DNS lookup is always re-evaluated, +so 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. +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). +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 +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 -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. +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 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 if `allow_stale` is -enabled, we will use data from any Consul server that is within 5 seconds -of the leader. +By default, [`allow_stale`](/docs/agent/options.html#allow_stale) is disabled, +meaning no stale results may be served. The default for +[`max_stale`](/docs/agent/options.html#max_stale) is 5 seconds. This means that +if [`allow_stale`](/docs/agent/options.html#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 downstream -of Consul which can be used to reduce the number of lookups and to amortize -the latency of doing a DNS lookup. By default, all TTLs are zero, +TTL values can be set to allow DNS results to be cached downstream of Consul. Higher +TTL values reduce the number of lookups on the Consul servers and speed lookups for +clients, at the cost of increasingly stale results. 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. +To enable caching of node lookups (e.g. "foo.node.consul"), we can set the +[`dns_config.node_ttl`](/docs/agent/options.html#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. +Service TTLs can be specified in a more granular fashion. You can set TTLs +per-service, with a wildcard TTL as the default. This is specified using the +[`dns_config.service_ttl`](/docs/agent/options.html#service_ttl) map. The "*" +service is the wildcard service. -This is specified using the `dns_config.service_ttl` map. The "*" service -is the wildcard service. For example, if we specify: +For example, a [`dns_config`](/docs/agent/options.html#dns_config) that provides +a wildcard TTL and a specific TTL for a service might look like this: ```javascript { @@ -70,6 +74,6 @@ is the wildcard service. For example, if we specify: } ``` -This sets all lookups to "web.service.consul" to use a 30 second TTL, +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.