status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Website: GH-730 links and clean-up for /docs/guides/dns-cache.html

This commit is contained in:
Ryan Breen 2015-02-25 10:45:21 -05:00
parent fa2328a07d
commit 669b9f61f9
1 changed files with 30 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
website/source/docs/guides/dns-cache.html.markdown
View File

@ -3,61 +3,65 @@ layout: "docs"
page_title: "DNS Caching" page_title: "DNS Caching"
sidebar_current: "docs-guides-dns-cache" sidebar_current: "docs-guides-dns-cache"
description: |- 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 # 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 integrate Consul into an existing infrastructure without any high-touch
integration. integration.
By default, Consul serves all DNS results with a 0 TTL value. This prevents 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 any caching. The advantage is that each DNS lookup is always re-evaluated,
and the most timely information is served. However this adds a latency hit 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 each lookup and can potentially exhaust the query throughput of a cluster.
For this reason, Consul provides a number of tuning parameters that can 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
Stale reads can be used to reduce latency and increase the throughput 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 These reads are strongly consistent but are limited by the throughput
of a single node. Doing a stale read allows any Consul server to 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 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 read scalability. Now any Consul server can service the request, so we
increase throughput by the number of servers in a cluster. increase throughput by the number of servers in a cluster.
The [settings](/docs/agent/options.html) used to control stale reads The [settings](/docs/agent/options.html) used to control stale reads
are `dns_config.allow_stale` which must be set to enable stale reads, are [`dns_config.allow_stale`](/docs/agent/options.html#allow_stale),
and `dns_config.max_stale` which limits how stale results are allowed to which must be set to enable stale reads, and
be. [`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. By default, [`allow_stale`](/docs/agent/options.html#allow_stale) is disabled,
The default for `max_stale` is 5 seconds. This means that if `allow_stale` is meaning no stale results may be served. The default for
enabled, we will use data from any Consul server that is within 5 seconds [`max_stale`](/docs/agent/options.html#max_stale) is 5 seconds. This means that
of the leader. 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
TTL values can be set to allow DNS results to be cached downstream TTL values can be set to allow DNS results to be cached downstream of Consul. Higher
of Consul which can be used to reduce the number of lookups and to amortize TTL values reduce the number of lookups on the Consul servers and speed lookups for
the latency of doing a DNS lookup. By default, all TTLs are zero, clients, at the cost of increasingly stale results. By default, all TTLs are zero,
preventing any caching. preventing any caching.
To enable caching of node lookups (e.g. "foo.node.consul"), we can set To enable caching of node lookups (e.g. "foo.node.consul"), we can set the
the `dns_config.node_ttl` value. This can be set to "10s" for example, [`dns_config.node_ttl`](/docs/agent/options.html#node_ttl) value. This can be set to
and all node lookups will serve results with a 10 second TTL. "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 Service TTLs can be specified in a more granular fashion. You can set TTLs
a TTL on a per-service level, and additionally a wildcard can be specified per-service, with a wildcard TTL as the default. This is specified using the
that matches if there is no specific service TTL provided. [`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 For example, a [`dns_config`](/docs/agent/options.html#dns_config) that provides
is the wildcard service. For example, if we specify: a wildcard TTL and a specific TTL for a service might look like this:
```javascript ```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 while lookups to "db.service.consul" or "api.service.consul" will use the
5 second TTL from the wildcard. 5 second TTL from the wildcard.