Merge pull request #11838 from hashicorp/partitions-dns-docs
docs: Update dns sections for partition query format and virtual IPs
This commit is contained in:
Kyle Havlovitz
GitHub
commit
d2244a719f
|
|
@ -1459,7 +1459,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
|
|||
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 /> -
|
||||
- `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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -255,6 +255,21 @@ and doesn't support tags. This DNS interface will be expanded over time.
|
|||
If you need more complex behavior, please use the
|
||||
[catalog API](/api/catalog).
|
||||
|
||||
### Service Virtual IP Lookups
|
||||
|
||||
To find the unique virtual IP allocated for a service:
|
||||
|
||||
```text
|
||||
<service>.virtual.<domain>
|
||||
```
|
||||
|
||||
This will return the unique virtual IP for any [Connect-capable](/docs/connect)
|
||||
service. Each Connect service has a virtual IP assigned to it by Consul - this is used
|
||||
by sidecar proxies for the [Transparent Proxy](/docs/connect/transparent-proxy) feature.
|
||||
|
||||
The virtual IP is also added to the service's [Tagged Addresses](/docs/discovery/services#tagged-addresses)
|
||||
under the `consul-virtual` tag.
|
||||
|
||||
### Ingress Service Lookups
|
||||
|
||||
To find ingress-enabled services:
|
||||
|
|
@ -335,37 +350,23 @@ using the [`advertise-wan`](/docs/agent/options#_advertise-wan) and
|
|||
[`translate_wan_addrs`](/docs/agent/options#translate_wan_addrs) configuration
|
||||
options.
|
||||
|
||||
## Namespaced Services <EnterpriseAlert inline />
|
||||
## Namespaced/Partitioned Services <EnterpriseAlert inline />
|
||||
|
||||
Consul Enterprise 1.7.0 added support for namespaces including resolving namespaced
|
||||
services via DNS. To maintain backwards compatibility existing queries can be used
|
||||
and these will resolve services within the `default` namespace. However, for resolving
|
||||
services from other namespaces the following form can be used:
|
||||
Consul Enterprise supports resolving namespaced and partitioned services via DNS.
|
||||
To maintain backwards compatibility existing queries can be used and these will
|
||||
resolve services within the `default` namespace and partition. However, for resolving
|
||||
services from other namespaces or partitions the following form can be used:
|
||||
|
||||
```text
|
||||
[tag.]<service>.service.<namespace>.<datacenter>.<domain>
|
||||
[tag.]<service>.service.<namespace>.ns.<partition>.ap.<datacenter>.dc.<domain>
|
||||
```
|
||||
|
||||
This is the canonical name of a Consul Enterprise service with all parts present. Like
|
||||
Consul OSS some parts may be omitted but which parts depend on the value of the
|
||||
[`prefer_namespace` configuration](/docs/agent/options#dns_prefer_namespace).
|
||||
|
||||
With `prefer_namespace` set to `true` the datacenter may be omitted and will be defaulted
|
||||
to the local agents datacenter:
|
||||
|
||||
```text
|
||||
[tag.]<service>.service.<namespace>.<domain>
|
||||
```
|
||||
|
||||
With `prefer_namespace` set to `false` the namespace may be omitted and will be defaulted
|
||||
to the `default` namespace:
|
||||
|
||||
```text
|
||||
[tag.]<service>.service.<datacenter>
|
||||
```
|
||||
|
||||
Finally, both the namespace and datacenter may be omitted and the service will be resolved
|
||||
in the `default` namespace and in the datacenter of the local agent.
|
||||
This is the canonical name of a Consul Enterprise service. Currently all parts must be
|
||||
present - in a future version (once the
|
||||
[`prefer_namespace` configuration](/docs/agent/options#dns_prefer_namespace) has been
|
||||
deprecated), the namespace, partition and datacenter components will become optional
|
||||
and may be individually omitted to default to the `default` namespace, local partition
|
||||
or local datacenter respectively.
|
||||
|
||||
## DNS with ACLs
|
||||
|
||||
|
|
@ -386,11 +387,11 @@ Consul will either accept or deny the request depending on whether the token
|
|||
has the appropriate authorization. The following table describes the available
|
||||
DNS lookups and required policies when ACLs are enabled:
|
||||
|
||||
| Lookup | Type | Description | ACLs Required |
|
||||
| ---------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `*.node.consul` | [Node](#node-lookups) | Allow resolving DNS requests for the target node (i.e., `<target>.node.consul`) | [`node:read`](/docs/security/acl/acl-rules#node-rules) |
|
||||
| `*.service.consul`, `*.connect.consul`, `*.ingress.consul` | [Service: standard](#service-lookups) | Allow resolving DNS requests for target service (e.g., `<target>.service.consul`) instances running on ACL-authorized nodes | [`service:read`](/docs/security/acl/acl-rules#service-rules), [`node:read`](/docs/security/acl/acl-rules#node-rules) |
|
||||
| `*.query.consul` | [Service: prepared query](#prepared-query-lookups) | Allow resolving DNS requests for [service instances specified](/api/query#service-1) by the target prepared query (i.e., `<target>.query.consul`) running on ACL-authorized nodes | [`query:read`](/docs/security/acl/acl-rules#prepared-query-rules), [`service:read`](/docs/security/acl/acl-rules#service-rules), [`node:read`](/docs/security/acl/acl-rules#node-rules) |
|
||||
| Lookup | Type | Description | ACLs Required |
|
||||
| ------------------------------------------------------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `*.node.consul` | [Node](#node-lookups) | Allow resolving DNS requests for the target node (i.e., `<target>.node.consul`) | [`node:read`](/docs/security/acl/acl-rules#node-rules) |
|
||||
| `*.service.consul`, `*.connect.consul`, `*.ingress.consul`, `*.virtual.consul` | [Service: standard](#service-lookups) | Allow resolving DNS requests for target service (e.g., `<target>.service.consul`) instances running on ACL-authorized nodes | [`service:read`](/docs/security/acl/acl-rules#service-rules), [`node:read`](/docs/security/acl/acl-rules#node-rules) |
|
||||
| `*.query.consul` | [Service: prepared query](#prepared-query-lookups) | Allow resolving DNS requests for [service instances specified](/api/query#service-1) by the target prepared query (i.e., `<target>.query.consul`) running on ACL-authorized nodes | [`query:read`](/docs/security/acl/acl-rules#prepared-query-rules), [`service:read`](/docs/security/acl/acl-rules#service-rules), [`node:read`](/docs/security/acl/acl-rules#node-rules) |
|
||||
|
||||
For guidance on how to configure an appropriate token for DNS, refer to the
|
||||
securing Consul with ACLs guides for:
|
||||
|
|
|
|||
Loading…
Reference in New Issue