luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #663 from ryanbreen/master 

Grammatical cleanups to doc/agent/dns
This commit is contained in:
Ryan Uber 2015-01-31 10:38:43 -08:00
parent c560d02745 07bb5ea4ac
commit 50c478b34f
1 changed files with 54 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
website/source/docs/agent/dns.html.markdown
View File

@ -3,60 +3,63 @@ layout: "docs"
page_title: "DNS Interface" page_title: "DNS Interface"
sidebar_current: "docs-agent-dns" sidebar_current: "docs-agent-dns"
description: |- description: |-
One of the primary query interfaces for Consul is using DNS. The DNS interface allows applications to make use of service discovery without any high-touch integration with Consul. 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.
--- ---
# DNS Interface # DNS Interface
One of the primary query interfaces for Consul is DNS. One of the primary query interfaces for Consul is DNS.
The DNS interface allows applications to make use of service The DNS interface allows applications to make use of service
discovery without any high-touch integration with Consul. For discovery without any high-touch integration with Consul.
example, instead of making HTTP API requests to Consul,
a host can use the DNS server directly and just do a name lookup
for "redis.service.east-aws.consul".
This query automatically translates to a lookup of nodes that For example, instead of making HTTP API requests to Consul,
provide the redis service, are located in the "east-aws" datacenter, a host can use the DNS server directly via name lookups
and have no failing health checks. It's that simple! 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!
There are a number of [configuration options](/docs/agent/options.html) that There are a number of configuration options that are important for the DNS interface,
are important for the DNS interface. They are `client_addr`, `ports.dns`, `recursors`, specifically `client_addr`, `ports.dns`, `recursors`, `domain`, and `dns_config`. By default,
`domain`, and `dns_config`. By default Consul will listen on 127.0.0.1:8600 for DNS queries Consul will listen on 127.0.0.1:8600 for DNS queries in the "consul." domain, without support
in the "consul." domain, without support for DNS recursion. All queries are case-insensitive: a for further DNS recursion. Please consult the [documentation on configuration options](/docs/agent/options.html)
name lookup for `PostgreSQL.node.dc1.consul` will find all nodes named `postgresql`, for more details.
regardless of case.
There are a few ways to use the DNS interface. One option is to use a custom 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 DNS resolver library and point it at Consul. Another option is to set Consul
as the DNS server for a node, and provide `recursors` so that non-Consul queries as the DNS server for a node and provide `recursors` so that non-Consul queries
can also be resolved. The last method is to forward all queries for the "consul." can also be resolved. The last method is to forward all queries for the "consul."
domain to a Consul agent from the existing DNS server. To play with the DNS server domain to a Consul agent from the existing DNS server.
on the command line, dig can be used:
You can experiment with Consul's DNS server on the command line using tools such as `dig`:
$ dig @127.0.0.1 -p 8600 redis.service.dc1.consul. ANY $ 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`.
## Node Lookups ## Node Lookups
For Consul to resolve names, it relies on a very specific format for queries. To resolve names, Consul relies on a very specific format for queries.
There are fundamentally two types of queries, node lookups and service lookups. There are fundamentally two types of queries: node lookups and service lookups.
A node lookup is a simple query for the address of a named node, and takes on A node lookup, a simple query for the address of a named node, looks like this:
the following format:
<node>.node.<datacenter>.<domain> <node>.node.<datacenter>.<domain>
So, for example, if we have a "foo" node with default settings, we could look for For example, if we have a "foo" node with default settings, we could look for
"foo.node.dc1.consul." The datacenter is an optional part of the FQDN, and if not "foo.node.dc1.consul." The datacenter is an optional part of the FQDN: if not
provided defaults to the datacenter of the agent. So if we know "foo" is running in our provided, it defaults to the datacenter of the agent. If we know "foo" is running in
same datacenter, we can instead use "foo.node.consul." Alternatively, we can do a the same datacenter as our local agent, we can instead use "foo.node.consul." This
DNS lookup for nodes in other datacenters, with no additional effort. convention allows for terse syntax where appropriate while supporting queries of
nodes in remote datacenters as necessary.
For a node lookup, the only records returned are A records with the IP address of For a node lookup, the only records returned are A records containing the IP address of
the node. the node.
```text ```text
$ dig @127.0.0.1 -p 8600 foobar.node.consul ANY $ dig @127.0.0.1 -p 8600 foo.node.consul ANY
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 foobar.node.consul ANY ; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 foo.node.consul ANY
; (1 server found) ; (1 server found)
;; global options: +cmd ;; global options: +cmd
;; Got answer: ;; Got answer:
@ -65,10 +68,10 @@ $ dig @127.0.0.1 -p 8600 foobar.node.consul ANY
;; WARNING: recursion requested but not available ;; WARNING: recursion requested but not available
;; QUESTION SECTION: ;; QUESTION SECTION:
;foobar.node.consul. IN ANY ;foo.node.consul. IN ANY
;; ANSWER SECTION: ;; ANSWER SECTION:
foobar.node.consul. 0 IN A 10.1.10.12 foo.node.consul. 0 IN A 10.1.10.12
;; AUTHORITY SECTION: ;; AUTHORITY SECTION:
consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0 consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0
@ -76,9 +79,8 @@ consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0
## Service Lookups ## Service Lookups
A service lookup is the alternate type of query. It is used to query for service A service lookup is used to query for service providers. Service queries support
providers and supports two lookup methods: standard lookup, and strict two lookup methods: standard and strict [RFC 2782](https://tools.ietf.org/html/rfc2782).
[RFC 2782](https://tools.ietf.org/html/rfc2782) lookup.
### Standard Lookup ### Standard Lookup
@ -86,23 +88,25 @@ The format of a standard service lookup is:
[tag.]<service>.service[.datacenter][.domain] [tag.]<service>.service[.datacenter][.domain]
As with node lookups, the `datacenter` is optional, as is the `tag`. If no tag is The `tag` is optional, and, as with node lookups, the `datacenter` is as well. If no tag is
provided, then no filtering is done on tag. So, if we want to find any redis service provided, no filtering is done on tag. If no datacenter is provided, the datacenter of
providers in our local datacenter, we could lookup "redis.service.consul.", while this Consul agent is assumed.
if we care about the PostgreSQL master in a particular datacenter, we could lookup
"master.postgresql.service.dc2.consul." 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."
The DNS query system makes use of health check information to prevent routing 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 to unhealthy nodes. When a service query is made, any services failing their health
check, or failing a node system check, will be omitted from the results. To allow check or failing a node system check will be omitted from the results. To allow
for simple load balancing, the set of nodes returned is also randomized each time. for simple load balancing, the set of nodes returned is also randomized each time.
These simple mechanisms make it easy to use DNS along with application level retries These mechanisms make it easy to use DNS along with application-level retries
as a simple foundation for an auto-healing service oriented architecture. as the foundation for an auto-healing service oriented architecture.
For these lookups, both A and SRV records may be served. The SRV records will also For standard services queries, both A and SRV records are supported. SRV records
provide the port that a service is registered on, enabling services to avoid relying 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 on well-known ports. SRV records are only served if the client specifically requests
SRV records. them, like so:
```text ```text
$ dig @127.0.0.1 -p 8600 consul.service.consul SRV $ dig @127.0.0.1 -p 8600 consul.service.consul SRV
@ -134,15 +138,14 @@ The format for RFC 2782 SRV lookups is:
Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries should use Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries should use
underscores (_) as a prefix to the `service` and `protocol` values in a query to 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 prevent DNS collisions. The `protocol` value can be any of the tags for a
service or if the service has no tags, the value "tcp" should be used. If "tcp" service. If the service has no tags, "tcp" should be used. If "tcp"
is specified as the protocol, the query will not perform any tag filtering. 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 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. of the RFC style lookup is the same as the standard style of lookup.
Using RFC 2782 lookup, If you registered the service "rabbitmq" on port If you registered the service "rabbitmq" on port 5672 and tagged it with "amqp",
5672 and tagged it with "amqp" you would query the SRV record as you could make an RFC 2782 query for its SRV record as "_rabbitmq._amqp.service.consul":
"_rabbitmq._amqp.service.consul" as illustrated in the example below:
```text ```text
$ dig @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul SRV $ dig @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul SRV
@ -165,6 +168,8 @@ _rabbitmq._amqp.service.consul. 0 IN SRV 1 1 5672 rabbitmq.node1.dc1.consul.
rabbitmq.node1.dc1.consul. 0 IN A 10.1.11.20 rabbitmq.node1.dc1.consul. 0 IN A 10.1.11.20
``` ```
Again, note that the SRV record returns the port of the service as well as its IP.
### UDP Based DNS Queries ### UDP Based DNS Queries
When the DNS query is performed using UDP, Consul will truncate the results When the DNS query is performed using UDP, Consul will truncate the results