Merge pull request #10837 from jkirschner-hashicorp/improve-docs-dns-with-acl

Improve documentation around using DNS with ACLs Enabled

website/content/docs/discovery/dns.mdx

@@ -325,3 +325,34 @@ to the `default` namespace:
 
 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.
+
+## DNS with ACLs
+
+In order to use the DNS interface when
+[Access Control Lists (ACLs)](/docs/security/acl/acl-system)
+are enabled, you must first create ACL tokens with the necessary policies.
+
+Consul agents resolve DNS requests using one of the preconfigured tokens below,
+listed in order of precedence:
+
+1. The agent's [`default` token](/docs/agent/options#acl_tokens_default).
+2. The built-in [`anonymous` token](/docs/security/acl/acl-system#builtin-tokens).
+   Because the anonymous token is used when any request is made to Consul without
+   explicitly specifying a token, production deployments should not apply policies
+   needed for DNS to this token.
+
+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) |
+
+For guidance on how to configure an appropriate token for DNS, refer to the
+securing Consul with ACLs guides for:
+
+- [Production Environments](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#token-for-dns)
+- [Development Environments](https://learn.hashicorp.com/tutorials/consul/access-control-setup#additional-acl-configuration)

website/content/docs/security/acl/acl-system.mdx

@@ -22,6 +22,10 @@ To learn how to setup the ACL system on an existing Consul datacenter, use the [
 ## ACL System Overview
 
 The ACL system is designed to be easy to use and fast to enforce while providing administrative insight.
+The diagram below shows the relationships between most of the components of the ACL system:
+
+![ACL system component relationships](/img/acl-token-policy-rule-relationship.png)
+
 At the highest level, there are two major components to the ACL system:
 
 - **ACL Policies** - Policies allow the grouping of a set of rules into a logical unit that can be reused and linked with
@@ -237,7 +241,7 @@ The following table summarizes the ACL resources that are available for construc
 rules:
 
 | Resource                                            | Scope                                                                                                                                                                                                    |
-| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`acl`](/docs/acl/acl-rules#acl-resource-rules)     | Operations for managing the ACL system [ACL API](/api/acl/acl)                                                                                                                                           |
 | [`agent`](/docs/acl/acl-rules#agent-rules)          | Utility operations in the [Agent API](/api/agent), other than service and check registration                                                                                                             |
 | [`event`](/docs/acl/acl-rules#event-rules)          | Listing and firing events in the [Event API](/api/event)                                                                                                                                                 |