Skip to content

Commit

Permalink
docs: all enterprise locality labels now optional
Browse files Browse the repository at this point in the history
  • Loading branch information
jkirschner-hashicorp committed Sep 19, 2022
1 parent 1d7c82c commit b24b802
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 15 deletions.
3 changes: 3 additions & 0 deletions .changelog/14679.txt
Original file line number Diff line number Diff line change
@@ -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: <tag>.]<service>.service[.<namespace>.ns][.<partition>.ap][.<datacenter>.dc]<domain>`.
```
9 changes: 4 additions & 5 deletions website/content/docs/agent/config/config-files.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)) <EnterpriseAlert inline /> **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
- `prefer_namespace` ((#dns_prefer_namespace)) <EnterpriseAlert inline /> **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 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.
versions and will assume the single label is the datacenter.

- `domain` Equivalent to the [`-domain` command-line flag](/docs/agent/config/cli-flags#_domain).

Expand Down
43 changes: 33 additions & 10 deletions website/content/docs/discovery/dns.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -353,23 +353,46 @@ $ 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
[<tag>.]<service>.service.<namespace>.ns.<partition>.ap.<datacenter>.dc.<domain>
```
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,
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 all service lookup types except `.query`,
including `.service`, `.connect`, `.virtual`, and `.ingress`.
All three fields (`namespace`, `partition`, `datacenter`) are optional.
```text
[<tag>.]<service>.service[.<namespace>.ns][.<partition>.ap][.<datacenter>.dc]<domain>
```

#### Alternative formats for specifying namespace

Though the [canonical format](#canonical-format) is recommended for readability,
the following query formats may be used to specify namespace-only:

- Specify namespace and datacenter pair

```text
[<tag>.]<service>.service.<namespace>.<datacenter>.<domain>
```

- **Deprecated in Consul 1.11:**
Specify namespace-only if 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
[<tag>.]<service>.service.<namespace>.<domain>
```

### Prepared Query Lookups

Expand Down

0 comments on commit b24b802

Please sign in to comment.