diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx index 5925c35ee..06d340ccf 100644 --- a/website/content/docs/agent/options.mdx +++ b/website/content/docs/agent/options.mdx @@ -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)) - + - `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 diff --git a/website/content/docs/discovery/dns.mdx b/website/content/docs/discovery/dns.mdx index ef1b8a8be..5de36d932 100644 --- a/website/content/docs/discovery/dns.mdx +++ b/website/content/docs/discovery/dns.mdx @@ -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 +.virtual. +``` + +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 +## Namespaced/Partitioned Services -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... +[tag.].service..ns..ap..dc. ``` -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.. -``` - -With `prefer_namespace` set to `false` the namespace may be omitted and will be defaulted -to the `default` namespace: - -```text -[tag.].service. -``` - -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., `.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., `.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., `.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., `.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., `.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., `.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: