Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backport of Document that DNS lookups can target cluster peers into release/1.16.x #18026

Merged
merged 1 commit into from
Jul 5, 2023
Merged

Backport of Document that DNS lookups can target cluster peers into release/1.16.x #18026

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 36 additions & 2 deletions website/content/docs/services/discovery/dns-static-lookups.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,16 +97,18 @@ The DNS protocol limits the size of requests, even when performing DNS TCP queri
Consul randomizes DNS SRV records and ignores weights specified in service configurations when printing responses. If records are truncated, each client using weighted SRV responses may have partial and inconsistent views of instance weights. As a result, the request distribution may be skewed from the intended weights. We recommend calling the [`/catalog/nodes` API endpoint](/consul/api-docs/catalog#list-nodes) to retrieve the complete list of nodes. You can apply query parameters to API calls to sort and filter the results.

### Standard lookups
To perform standard service lookups, specify tags, the name of the service, datacenter, and domain using the following syntax to query for service providers:
To perform standard service lookups, specify tags, the name of the service, datacenter, cluster peer, and domain using the following syntax to query for service providers:

```text
[<tag>.]<service>.service[.<datacenter>].dc.<domain>
[<tag>.]<service>.service[.<datacenter>.dc][.<cluster-peer>.peer].<domain>
```

The `tag` subdomain is optional. It filters responses so that only service providers containing the tag appear.

The `datacenter` subdomain is optional. By default, Consul interrogates the querying agent's datacenter.

The `cluster-peer` name is optional, and specifies the [cluster peer](/consul/docs/connect/cluster-peering) whose [exported services](/consul/docs/connect/config-entries/exported-services) should be the target of the query.

By default, the lookups query in the `consul` domain. Refer to [Configure DNS Behaviors](/consul/docs/services/discovery/dns-configuration) for information about using alternate domains.

#### Standard lookup results
Expand Down Expand Up @@ -195,6 +197,38 @@ _rabbitmq._amqp.service.consul. 0 IN SRV 1 1 5672 rabbitmq.node1.dc1.consul.
;; ADDITIONAL SECTION:
rabbitmq.node1.dc1.consul. 0 IN A 10.1.11.20
```

You can also perform RFC 2782 lookups that target a specific [cluster peer](/consul/docs/connect/cluster-peering) or datacenter by including `<datacenter>.dc` or `<cluster-peer>.peer` in the query labels:

```text
_<service>._<tag>[.service][.<datacenter>.dc][.<cluster-peer>.peer].<domain>
```

The following example queries the `redis` service tagged with `tcp` for the cluster peer `phx1`, which returns two instances, one at `10.1.11.83:29081` and one at `10.1.11.86:29142`:

```shell-session
dig @127.0.0.1 -p 8600 _redis._tcp.service.phx1.peer.consul SRV

; <<>> DiG 9.18.15 <<>> @127.0.0.1 -p 8600 _redis._tcp.service.phx1.peer.consul SRV
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 40572
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 2

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
;; QUESTION SECTION:
;_redis._tcp.service.phx1.peer.consul. IN SRV

;; ANSWER SECTION:
_redis._tcp.service.phx1.peer.consul. 0 IN SRV 1 1 29081 0a000d53.addr.consul.
_redis._tcp.service.phx1.peer.consul. 0 IN SRV 1 1 29142 0a010d56.addr.consul.

;; ADDITIONAL SECTION:
0a000d53.addr.consul. 0 IN A 10.1.11.83
0a010d56.addr.consul. 0 IN A 10.1.11.86
```

#### SRV responses for hosts in the .addr subdomain

If a service registered with Consul is configured with an explicit IP address or addresses in the [`address`](/consul/docs/services/configuration/services-configuration-reference#address) or [`tagged_address`](/consul/docs/services/configuration/services-configuration-reference#tagged_address) parameter, then Consul returns the hostname in the target field of the answer section for the DNS SRV query according to the following format:
Expand Down