github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #13999 from hashicorp/docs/improve-dns-lookup-variable-consistency 

docs: improve consistency of DNS lookup variables
pull/14311/head
Jared Kirschner 2022-08-23 09:53:04 -04:00 committed by GitHub
parent 1200e83c3b 589e7cfab4
commit eb645453d6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
website/content/docs/discovery/dns.mdx
View File

@ -52,7 +52,7 @@ 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: A node lookup, a simple query for the address of a named node, looks like this:
```text ```text
<node>.node[.datacenter].<domain> <node>.node[.<datacenter>].<domain>
``` ```
For example, if we have a `foo` node with default settings, we could For example, if we have a `foo` node with default settings, we could
@ -79,16 +79,16 @@ $ dig @127.0.0.1 -p 8600 foo.node.consul ANY
;; WARNING: recursion requested but not available ;; WARNING: recursion requested but not available
;; QUESTION SECTION: ;; QUESTION SECTION:
;foo.node.consul. IN ANY ;foo.node.consul. IN ANY
;; ANSWER SECTION: ;; ANSWER SECTION:
foo.node.consul. 0 IN A 10.1.10.12 foo.node.consul. 0 IN A 10.1.10.12
foo.node.consul. 0 IN TXT "meta_key=meta_value" foo.node.consul. 0 IN TXT "meta_key=meta_value"
foo.node.consul. 0 IN TXT "value only" foo.node.consul. 0 IN TXT "value only"
;; 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
``` ```
By default the TXT records value will match the node's metadata key-value By default the TXT records value will match the node's metadata key-value
@ -121,7 +121,7 @@ it is recommended to use the HTTP API to retrieve the list of nodes.
The format of a standard service lookup is: The format of a standard service lookup is:
```text ```text
[tag.]<service>.service[.datacenter].<domain> [<tag>.]<service>.service[.<datacenter>].<domain>
``` ```
The `tag` is optional, and, as with node lookups, the `datacenter` is as The `tag` is optional, and, as with node lookups, the `datacenter` is as
@ -157,26 +157,37 @@ $ dig @127.0.0.1 -p 8600 consul.service.consul SRV
;; WARNING: recursion requested but not available ;; WARNING: recursion requested but not available
;; QUESTION SECTION: ;; QUESTION SECTION:
;consul.service.consul. IN SRV ;consul.service.consul. IN SRV
;; ANSWER SECTION: ;; ANSWER SECTION:
consul.service.consul. 0 IN SRV 1 1 8300 foobar.node.dc1.consul. consul.service.consul. 0 IN SRV 1 1 8300 foobar.node.dc1.consul.
;; ADDITIONAL SECTION: ;; ADDITIONAL SECTION:
foobar.node.dc1.consul. 0 IN A 10.1.10.12 foobar.node.dc1.consul. 0 IN A 10.1.10.12
``` ```
### RFC 2782 Lookup ### RFC 2782 Lookup
The format for RFC 2782 SRV lookups is: Valid formats for RFC 2782 SRV lookups depend on
whether you want to filter results based on a service tag:
_<service>._<protocol>[.service][.datacenter][.domain] - No filtering on service tag
Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries should use ```text
underscores, `_`, as a prefix to the `service` and `protocol` values in a query to _<service>._tcp[.service][.<datacenter>].<domain>
prevent DNS collisions. The `protocol` value can be any of the tags for a ```
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. - Filtering on service tag specified in the RFC 2782 protocol field
```text
_<service>._<tag>[.service][.<datacenter>].<domain>
```
Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries must
prepend an underscore (`_`) to the `service` and `protocol` values in a query to
prevent DNS collisions.
To perform no tag-based filtering, specify `tcp` in the RFC 2782 protocol field.
To filter results on a service tag, specify the tag in the RFC 2782 protocol field.
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.
@ -196,13 +207,13 @@ $ dig @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul SRV
;; WARNING: recursion requested but not available ;; WARNING: recursion requested but not available
;; QUESTION SECTION: ;; QUESTION SECTION:
;_rabbitmq._amqp.service.consul. IN SRV ;_rabbitmq._amqp.service.consul. IN SRV
;; ANSWER SECTION: ;; ANSWER SECTION:
_rabbitmq._amqp.service.consul. 0 IN SRV 1 1 5672 rabbitmq.node1.dc1.consul. _rabbitmq._amqp.service.consul. 0 IN SRV 1 1 5672 rabbitmq.node1.dc1.consul.
;; ADDITIONAL SECTION: ;; ADDITIONAL SECTION:
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. Again, note that the SRV record returns the port of the service as well as its IP.
@ -328,7 +339,7 @@ $ echo -n "20010db800010002cafe000000001337" | perl -ne 'printf join(":", unpack
The format of a prepared query lookup is: The format of a prepared query lookup is:
```text ```text
<query or name>.query[.datacenter].<domain> <query or name>.query[.<datacenter>].<domain>
``` ```
The `datacenter` is optional, and if not provided, the datacenter of this Consul The `datacenter` is optional, and if not provided, the datacenter of this Consul
@ -376,7 +387,7 @@ If you need more complex behavior, please use the
To find the unique virtual IP allocated for a service: To find the unique virtual IP allocated for a service:
```text ```text
<service>.virtual[.peer].<domain> <service>.virtual[.<peer>].<domain>
``` ```
This will return the unique virtual IP for any [Connect-capable](/docs/connect) This will return the unique virtual IP for any [Connect-capable](/docs/connect)
@ -439,14 +450,14 @@ The following responses are returned:
``` ```
;; QUESTION SECTION: ;; QUESTION SECTION:
;consul.service.test-domain. IN SRV ;consul.service.test-domain. IN SRV
;; ANSWER SECTION: ;; ANSWER SECTION:
consul.service.test-domain. 0 IN SRV 1 1 8300 machine.node.dc1.test-domain. consul.service.test-domain. 0 IN SRV 1 1 8300 machine.node.dc1.test-domain.
;; ADDITIONAL SECTION: ;; ADDITIONAL SECTION:
machine.node.dc1.test-domain. 0 IN A 127.0.0.1 machine.node.dc1.test-domain. 0 IN A 127.0.0.1
machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment=" machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment="
``` ```
-> **PTR queries:** Responses to PTR queries (`<ip>.in-addr.arpa.`) will always use the -> **PTR queries:** Responses to PTR queries (`<ip>.in-addr.arpa.`) will always use the
@ -479,7 +490,7 @@ resolve services within the `default` namespace and partition. However, for reso
services from other namespaces or partitions the following form can be used: services from other namespaces or partitions the following form can be used:
```text ```text
[tag.]<service>.service.<namespace>.ns.<partition>.ap.<datacenter>.dc.<domain> [<tag>.]<service>.service.<namespace>.ns.<partition>.ap.<datacenter>.dc.<domain>
``` ```
This sequence is the canonical naming convention of a Consul Enterprise service. At least two of the following This sequence is the canonical naming convention of a Consul Enterprise service. At least two of the following
@ -491,14 +502,14 @@ fields must be present:
For imported lookups, only the namespace and peer need to be specified as the partition can be inferred from the peering: For imported lookups, only the namespace and peer need to be specified as the partition can be inferred from the peering:
```text ```text
<service>.virtual[.namespace][.peer].<domain> <service>.virtual[.<namespace>].<peer>.<domain>
``` ```
For node lookups, only the partition and datacenter need to be specified as nodes cannot be For node lookups, only the partition and datacenter need to be specified as nodes cannot be
namespaced. namespaced.
```text ```text
[tag.]<node>.node.<partition>.ap.<datacenter>.dc.<domain> [<tag>.]<node>.node.<partition>.ap.<datacenter>.dc.<domain>
``` ```
## DNS with ACLs ## DNS with ACLs