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

[hc-github-team-consul-core]

Backport

This PR is auto-generated from #17990 to be assessed for backporting due to the inclusion of the label backport/1.16.

🚨

Warning automatic cherry-pick of commits failed. If the first commit failed,
you will see a blank no-op commit below. If at least one commit succeeded, you
will see the cherry-picked commits up to, not including, the commit where
the merge conflict occurred.

The person who merged in the original PR is:
@david-yu
This person should manually cherry-pick the original PR into a new backport PR,
and close this one when the manual backport PR is merged in.

merge conflict error: unable to process merge commit: "22de906da45acb705ca130bad950448306fb2216", automatic backport requires rebase workflow

The below text is copied from the body of the original PR.

---

Description

Static DNS lookups, in addition to explicitly targeting a datacenter, can target a cluster peer. This was added in 95dc0c7 (1.15.0) but didn't make the documentation.

The driving function for the behavior change is parseLocality here:

consul/agent/dns_oss.go

Lines 25 to 44 in 0b1299c

	func (d *DNSServer) parseLocality(labels []string, cfg *dnsConfig) (queryLocality, bool) {
	locality := queryLocality{
	EnterpriseMeta: d.defaultEnterpriseMeta,
	}
	switch len(labels) {
	case 2, 4:
	// Support the following formats:
	// - [.<datacenter>.dc]
	// - [.<peer>.peer]
	for i := 0; i < len(labels); i += 2 {
	switch labels[i+1] {
	case "dc":
	locality.datacenter = labels[i]
	case "peer":
	locality.peer = labels[i]
	default:
	return queryLocality{}, false
	}
	}

The biggest documentation change I've proposed 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. This more matches my understanding of how to show that they have to be added as pairs for the directed lookups to work.

Testing & Reproduction steps

Documentation-only

Links

parseLocality function:

consul/agent/dns_oss.go

Line 25 in 0b1299c

func (d *DNSServer) parseLocality(labels []string, cfg *dnsConfig) (queryLocality, bool) {

Exported Services docs: https://developer.hashicorp.com/consul/docs/connect/config-entries/exported-services

Cluster Peering overview: https://developer.hashicorp.com/consul/docs/connect/cluster-peering

PR Checklist

• updated test coverage
• external facing docs updated
• appropriate backport labels added
• not a security concern

---

Overview of commits

• 4b1ed38 - 22de906 - c0c3564

[github-team-consul-core-pr-approver]

Auto approved Consul Bot automated PR