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

222 lines
9.0 KiB
Markdown
Raw Normal View History

2014-02-19 19:05:42 +00:00
---
layout: "docs"
page_title: "DNS Interface"
sidebar_current: "docs-agent-dns"
description: |-
2015-01-31 04:32:57 +00:00
One of the primary query interfaces for Consul is DNS. The DNS interface allows applications to make use of service discovery without any high-touch integration with Consul.
2014-02-19 19:05:42 +00:00
---
# DNS Interface
2014-11-26 13:32:19 +00:00
One of the primary query interfaces for Consul is DNS.
2014-02-19 19:05:42 +00:00
The DNS interface allows applications to make use of service
discovery without any high-touch integration with Consul.
2014-02-19 19:05:42 +00:00
For example, instead of making HTTP API requests to Consul,
a host can use the DNS server directly via name lookups
like "redis.service.east-aws.consul". This query automatically
translates to a lookup of nodes that provide the redis service,
are located in the "east-aws" datacenter, and have no failing health checks.
It's that simple!
2014-02-19 19:05:42 +00:00
There are a number of configuration options that are important for the DNS interface,
specifically [`client_addr`](/docs/agent/options.html#client_addr),
[`ports.dns`](/docs/agent/options.html#dns_port), [`recursors`](/docs/agent/options.html#recursors),
[`domain`](/docs/agent/options.html#domain), and [`dns_config`](/docs/agent/options.html#dns_config).
By default, Consul will listen on 127.0.0.1:8600 for DNS queries in the "consul."
domain, without support for further DNS recursion. Please consult the
[documentation on configuration options](/docs/agent/options.html),
specifically the configuration items linked above, for more details.
2014-02-19 19:05:42 +00:00
There are a few ways to use the DNS interface. One option is to use a custom
DNS resolver library and point it at Consul. Another option is to set Consul
as the DNS server for a node and provide a
[`recursors`](/docs/agent/options.html#recursors) configuration so that non-Consul queries
2014-02-19 19:05:42 +00:00
can also be resolved. The last method is to forward all queries for the "consul."
2015-01-31 17:51:28 +00:00
domain to a Consul agent from the existing DNS server.
You can experiment with Consul's DNS server on the command line using tools such as `dig`:
2014-02-19 19:05:42 +00:00
$ dig @127.0.0.1 -p 8600 redis.service.dc1.consul. ANY
Note that in DNS, all queries are case-insensitive. A lookup of `PostgreSQL.node.dc1.consul`
will find all nodes named `postgresql`.
2014-02-19 19:05:42 +00:00
## Node Lookups
2015-01-31 17:51:28 +00:00
To resolve names, Consul relies on a very specific format for queries.
There are fundamentally two types of queries: node lookups and service lookups.
A node lookup, a simple query for the address of a named node, looks like this:
2014-02-19 19:05:42 +00:00
<node>.node[.datacenter].<domain>
2014-02-19 19:05:42 +00:00
2015-01-31 17:51:28 +00:00
For example, if we have a "foo" node with default settings, we could look for
2015-01-31 18:17:43 +00:00
"foo.node.dc1.consul." The datacenter is an optional part of the FQDN: if not
2015-01-31 17:51:28 +00:00
provided, it defaults to the datacenter of the agent. If we know "foo" is running in
the same datacenter as our local agent, we can instead use "foo.node.consul." This
2015-01-31 18:17:43 +00:00
convention allows for terse syntax where appropriate while supporting queries of
2015-01-31 17:51:28 +00:00
nodes in remote datacenters as necessary.
2014-02-19 19:05:42 +00:00
2015-01-31 17:51:28 +00:00
For a node lookup, the only records returned are A records containing the IP address of
2014-02-19 19:05:42 +00:00
the node.
```text
2015-01-31 17:51:28 +00:00
$ dig @127.0.0.1 -p 8600 foo.node.consul ANY
2014-02-19 19:05:42 +00:00
2015-01-31 17:51:28 +00:00
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 foo.node.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 24355
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 0
;; WARNING: recursion requested but not available
2014-02-19 19:05:42 +00:00
;; QUESTION SECTION:
2015-01-31 17:51:28 +00:00
;foo.node.consul. IN ANY
2014-02-19 19:05:42 +00:00
;; ANSWER SECTION:
2015-01-31 17:51:28 +00:00
foo.node.consul. 0 IN A 10.1.10.12
2014-02-19 19:05:42 +00:00
;; AUTHORITY SECTION:
consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0
```
2014-02-19 19:05:42 +00:00
## Service Lookups
2015-01-31 18:36:31 +00:00
A service lookup is used to query for service providers. Service queries support
2015-01-31 17:51:28 +00:00
two lookup methods: standard and strict [RFC 2782](https://tools.ietf.org/html/rfc2782).
2014-02-19 19:05:42 +00:00
2014-11-26 13:32:19 +00:00
### Standard Lookup
2014-08-18 19:45:56 +00:00
2014-11-26 13:32:19 +00:00
The format of a standard service lookup is:
2014-08-18 19:45:56 +00:00
[tag.]<service>.service[.datacenter].<domain>
2014-02-19 19:05:42 +00:00
2015-01-31 18:17:43 +00:00
The `tag` is optional, and, as with node lookups, the `datacenter` is as well. If no tag is
2015-01-31 17:51:28 +00:00
provided, no filtering is done on tag. If no datacenter is provided, the datacenter of
this Consul agent is assumed.
If we want to find any redis service providers in our local datacenter, we could query
"redis.service.consul." If we want to find the PostgreSQL master in a particular datacenter,
we could query "master.postgresql.service.dc2.consul."
2014-02-19 19:05:42 +00:00
The DNS query system makes use of health check information to prevent routing
to unhealthy nodes. When a service query is made, any services failing their health
2015-01-31 17:51:28 +00:00
check or failing a node system check will be omitted from the results. To allow
2014-02-19 19:05:42 +00:00
for simple load balancing, the set of nodes returned is also randomized each time.
2015-01-31 18:17:43 +00:00
These mechanisms make it easy to use DNS along with application-level retries
2015-01-31 17:51:28 +00:00
as the foundation for an auto-healing service oriented architecture.
2014-02-19 19:05:42 +00:00
2015-01-31 17:51:28 +00:00
For standard services queries, both A and SRV records are supported. SRV records
provide the port that a service is registered on, enabling clients to avoid relying
2014-04-08 19:18:05 +00:00
on well-known ports. SRV records are only served if the client specifically requests
2015-01-31 17:51:28 +00:00
them, like so:
2014-02-19 19:05:42 +00:00
```text
$ dig @127.0.0.1 -p 8600 consul.service.consul SRV
2014-02-19 19:05:42 +00:00
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 consul.service.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 50483
;; flags: qr aa rd; QUERY: 1, ANSWER: 3, AUTHORITY: 1, ADDITIONAL: 1
;; WARNING: recursion requested but not available
2014-02-19 19:05:42 +00:00
;; QUESTION SECTION:
;consul.service.consul. IN SRV
2014-02-19 19:05:42 +00:00
;; ANSWER SECTION:
consul.service.consul. 0 IN SRV 1 1 8300 foobar.node.dc1.consul.
2014-02-19 19:05:42 +00:00
;; ADDITIONAL SECTION:
foobar.node.dc1.consul. 0 IN A 10.1.10.12
```
2014-02-19 19:05:42 +00:00
2014-11-26 13:32:19 +00:00
### RFC 2782 Lookup
2014-08-18 19:45:56 +00:00
2014-11-26 13:32:19 +00:00
The format for RFC 2782 SRV lookups is:
2014-08-18 19:45:56 +00:00
2014-09-24 23:59:43 +00:00
_<service>._<protocol>.service[.datacenter][.domain]
2014-08-18 19:45:56 +00:00
2014-11-26 13:32:19 +00:00
Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries should use
2014-08-18 19:45:56 +00:00
underscores (_) as a prefix to the `service` and `protocol` values in a query to
prevent DNS collisions. The `protocol` value can be any of the tags for a
2015-01-31 17:59:03 +00:00
service. If the service has no tags, "tcp" should be used. If "tcp"
2014-08-18 19:45:56 +00:00
is specified as the protocol, the query will not perform any tag filtering.
Other than the query format and default "tcp" protocol/tag value, the behavior
of the RFC style lookup is the same as the standard style of lookup.
2015-01-31 17:59:03 +00:00
If you registered the service "rabbitmq" on port 5672 and tagged it with "amqp",
you could make an RFC 2782 query for its SRV record as "_rabbitmq._amqp.service.consul":
2014-08-18 19:45:56 +00:00
```text
$ dig @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul SRV
2014-08-18 19:45:56 +00:00
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 52838
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available
2014-08-18 19:45:56 +00:00
;; QUESTION SECTION:
;_rabbitmq._amqp.service.consul. IN SRV
2014-08-18 19:45:56 +00:00
;; ANSWER SECTION:
_rabbitmq._amqp.service.consul. 0 IN SRV 1 1 5672 rabbitmq.node1.dc1.consul.
2014-08-18 19:45:56 +00:00
;; ADDITIONAL SECTION:
rabbitmq.node1.dc1.consul. 0 IN A 10.1.11.20
```
2014-08-18 19:45:56 +00:00
2015-01-31 17:59:03 +00:00
Again, note that the SRV record returns the port of the service as well as its IP.
### Prepared Query Lookups
The format of a prepared query lookup is:
<query or name>.query[.datacenter].<domain>
The `datacenter` is optional, and if not provided, the datacenter of this Consul
agent is assumed.
The `query or name` is the ID or given name of an existing
[Prepared Query](/docs/agent/http/query.html). These behave like standard service
queries but provide a much richer set of features, such as filtering by multiple
tags and automatically failing over to look for services in remote datacenters if
no healthy nodes are available in the local datacenter. Consul 0.6.4 and later also
added support for [prepared query templates](/docs/agent/http/query.html#templates)
which can match names using a prefix match, allowing one template to apply to
potentially many services.
To allow for simple load balancing, the set of nodes returned is randomized each time.
Both A and SRV records are supported. SRV records provide the port that a service is
registered on, enabling clients to avoid relying on well-known ports. SRV records are
only served if the client specifically requests them.
2014-08-18 19:45:56 +00:00
### UDP Based DNS Queries
When the DNS query is performed using UDP, Consul will truncate the results
without setting the truncate bit. This is to prevent a redundant lookup over
2014-11-26 13:32:19 +00:00
TCP that generates additional load. If the lookup is done over TCP, the results
are not truncated.
2014-02-19 19:05:42 +00:00
2014-06-09 00:26:41 +00:00
## 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).
## WAN Address Translation
2016-05-29 17:24:44 +00:00
By default, Consul DNS queries will return a node's local address, even when
being queried from a remote datacenter. If you need to use a different address
to reach a node from outside its datacenter, you can configure this behavior
using the [`advertise-wan`](/docs/agent/options.html#_advertise-wan) and
[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs) configuration
options.