website: Documenting DNS settings
This commit is contained in:
Armon Dadgar
parent
8d4c0aa0ce
commit
3af3f40434
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
74
website/source/docs/guides/dns-cache.html.markdown
Normal file
74
website/source/docs/guides/dns-cache.html.markdown
Normal file
|
|
@ -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.
|
||||
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue