Document that DNS lookups can target cluster peers (#17990)

Static DNS lookups, in addition to explicitly targeting a datacenter, can target a cluster peer. This was added in 95dc0c7 but didn't make the documentation. The driving function for the change is `parseLocality` here: https://github.com/hashicorp/consul/blob/0b1299c28d8127129d61310ee4280055298438e0/agent/dns_oss.go#L25 The biggest change in this is to adjust the standard lookup syntax to tie `.<datacenter>` to `.dc` as required-together, and to append in the similar `.<cluster-peer>.peer` optional argument, both to A record and SRV record lookups. Co-authored-by: David Yu <[email protected]>
hashicorp · Jul 5, 2023 · 7689a5e · 7689a5e
1 parent 548829a
commit 7689a5e
Showing 1 changed file with 36 additions and 2 deletions.
diff --git a/website/content/docs/services/discovery/dns-static-lookups.mdx b/website/content/docs/services/discovery/dns-static-lookups.mdx
@@ -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
@@ -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: