diff --git a/.changelog/14679.txt b/.changelog/14679.txt new file mode 100644 index 0000000000..601fd6c760 --- /dev/null +++ b/.changelog/14679.txt @@ -0,0 +1,3 @@ +```release-note:improvement +dns: **(Enterprise Only)** All enterprise locality labels are now optional in DNS lookups. For example, service lookups support the following format: .].service[..ns][..ap][..dc]`. +``` diff --git a/website/content/docs/agent/config/config-files.mdx b/website/content/docs/agent/config/config-files.mdx index 708489cfc3..be94d0bf53 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -1344,13 +1344,12 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." equivalent to "no max age". To get a fresh value from the cache use a very small value of `1ns` instead of 0. - - `prefer_namespace` ((#dns_prefer_namespace)) **Deprecated in - Consul 1.11. Use the [canonical DNS format](/docs/discovery/dns#namespaced-partitioned-services) instead.** - - When set to true, in a DNS query for a service, the label between the domain - and the `service` label will be treated as a namespace name instead of a datacenter. - When set to false, the default, the behavior will be the same as non-Enterprise - versions and will assume the label is the datacenter. See: [this section](/docs/discovery/dns#namespaced-services) - for more details. + - `prefer_namespace` ((#dns_prefer_namespace)) **Deprecated in Consul 1.11. + Use the [canonical DNS format for enterprise service lookups](/docs/discovery/dns#service-lookups-for-consul-enterprise) instead.** - + When set to `true`, in a DNS query for a service, a single label between the domain + and the `service` label is treated as a namespace name instead of a datacenter. + When set to `false`, the default, the behavior is the same as non-Enterprise + versions and treats the single label as the datacenter. - `domain` Equivalent to the [`-domain` command-line flag](/docs/agent/config/cli-flags#_domain). diff --git a/website/content/docs/discovery/dns.mdx b/website/content/docs/discovery/dns.mdx index 4e110f1f65..29f3e9645b 100644 --- a/website/content/docs/discovery/dns.mdx +++ b/website/content/docs/discovery/dns.mdx @@ -186,13 +186,13 @@ foobar.node.dc1.consul. 0 IN A 10.1.10.12 Valid formats for RFC 2782 SRV lookups depend on whether you want to filter results based on a service tag: -- No filtering on service tag +- No filtering on service tag: ```text _._tcp[.service][.]. ``` -- Filtering on service tag specified in the RFC 2782 protocol field +- Filtering on service tag specified in the RFC 2782 protocol field: ```text _._[.service][.]. @@ -353,15 +353,8 @@ $ echo -n "20010db800010002cafe000000001337" | perl -ne 'printf join(":", unpack By default, all service lookups use the `default` namespace within the partition and datacenter of the Consul agent that received the DNS query. - -Use the following query format to specify a namespace, partition, and/or datacenter -for all service lookup types except `.query`, -including `.service`, `.connect`, `.virtual`, and `.ingress`. -At least two of those three fields (`namespace`, `partition`, `datacenter`) -must be specified. -```text -[.].service..ns..ap..dc. -``` +To lookup services in another namespace, partition, and/or datacenter, +use the [canonical format](#canonical-format). Consul server agents are in the `default` partition. If DNS queries are addressed to Consul server agents, @@ -369,7 +362,37 @@ service lookups to non-`default` partitions must explicitly specify the partition of the target service. To lookup services imported from a cluster peer, -use a [service virtual IP lookups for Consul Enterprise](#service-virtual-ip-lookups-for-consul-enterprise) instead. +refer to [service virtual IP lookups for Consul Enterprise](#service-virtual-ip-lookups-for-consul-enterprise) instead. + +#### Canonical format + +Use the following query format to specify namespace, partition, and/or datacenter +for `.service`, `.connect`, `.virtual`, and `.ingress` service lookup types. +All three fields (`namespace`, `partition`, `datacenter`) are optional. +```text +[.].service[..ns][..ap][..dc] +``` + +#### Alternative formats for specifying namespace + +Though the [canonical format](#canonical-format) is recommended for readability, +you can use the following query formats specify namespace but not partition: + +- Specify both namespace and datacenter: + + ```text + [.].service... + ``` + +- **Deprecated in Consul 1.11:** + Specify namespace without a datacenter, + which requires that DNS queries are addressed to a Consul agent with + [`dns_config.prefer_namespace`](/docs/agent/config/config-files#dns_prefer_namespace) + set to `true`: + + ```text + [.].service.. + ``` ### Prepared Query Lookups