docs: Document .addr DNS domain in SRV responses (#12056)

Document `.addr` DNS subdomain that can be returned in SRV response
records.

Co-authored-by: Neena Pemmaraju <neena@hashicorp.com>
This commit is contained in:
Blake Covarrubias 2022-01-19 09:45:30 -08:00 committed by GitHub
parent 48ace89c6a
commit 1495a1f111
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 116 additions and 0 deletions

View File

@ -207,6 +207,122 @@ 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.
#### SRV response for hosts in the .addr subdomain
If a service registered to Consul has an explicit IP [`address`](/api-docs/agent/service#address)
or tagged address(es) defined on the service registration, the hostname returned
in the target field of the answer section for the DNS SRV query for the service
will be in the format of `<hexadecimal-encoded IP>.addr.<datacenter>.consul`.
<Tabs>
<Tab heading="IPv4">
In the example below, the `rabbitmq` service has been registered with an explicit
IPv4 address of `192.0.2.10`.
<CodeTabs heading="Service defined with explicit IPv4 address in agent config" filename="agent-config.hcl">
```hcl
node_name = "node1"
services {
name = "rabbitmq"
address = "192.0.2.10"
port = 5672
}
```
```json
{
"node_name": "node1",
"services": [
{
"name": "rabbitmq",
"address": "192.0.2.10",
"port": 5672
}
]
}
```
</CodeTabs>
When performing an SRV query for this service, the SRV response contains a single
record with a hostname in the format of `<hexadecimal-encoded IP>.addr.<datacenter>.consul`.
```shell-session
$ dig @127.0.0.1 -p 8600 -t srv _rabbitmq._tcp.service.consul +short
1 1 5672 c000020a.addr.dc1.consul.
```
In this example, the hex-encoded IP from the returned hostname is `c000020a`.
Converting each hex octet to decimal reveals the IP address that was specified
in the service registration.
```shell-session
$ echo -n "c000020a" | perl -ne 'printf("%vd\n", pack("H*", $_))'
192.0.2.10
```
</Tab>
<Tab heading="IPv6">
In the example below, the `rabbitmq` service has been registered with an explicit
IPv6 address of `2001:db8:1:2:cafe::1337`.
<CodeTabs heading="Service defined with explicit IPv6 address in agent config" filename="agent-config.hcl">
```hcl
node_name = "node1"
services {
name = "rabbitmq"
address = "2001:db8:1:2:cafe::1337"
port = 5672
}
```
```json
{
"node_name": "node1",
"services": [
{
"name": "rabbitmq",
"address": "2001:db8:1:2:cafe::1337",
"port": 5672
}
]
}
```
</CodeTabs>
When performing an SRV query for this servie, the SRV response contains a single
record with a hostname in the format of `<hexadecimal-encoded IP>.addr.<datacenter>.consul`.
```shell-session
$ dig @127.0.0.1 -p 8600 -t srv _rabbitmq._tcp.service.consul +short
1 1 5672 20010db800010002cafe000000001337.addr.dc1.consul.
```
In this example, the hex-encoded IP from the returned hostname is
`20010db800010002cafe000000001337`. This is the fully expanded IPv6 address with
colon separators removed.
The following command re-adds the colon separators to display the fully expanded
IPv6 address that was specified in the service registration.
```shell-session
$ echo -n "20010db800010002cafe000000001337" | perl -ne 'printf join(":", unpack("(A4)*", $_))."\n"'
2001:0db8:0001:0002:cafe:0000:0000:1337
```
</Tab>
</Tabs>
### Prepared Query Lookups
The format of a prepared query lookup is: