diff --git a/website/content/docs/configuration/consul.mdx b/website/content/docs/configuration/consul.mdx
index fd5e05df90d..d375eb80b11 100644
--- a/website/content/docs/configuration/consul.mdx
+++ b/website/content/docs/configuration/consul.mdx
@@ -116,9 +116,10 @@ agents.
- `token` `(string: "")` - Specifies the token used to provide a per-request ACL
token. This option overrides the Consul Agent's default token. If the token is
- not set here or on the Consul agent, it will default to Consul's anonymous policy,
- which may or may not allow writes. Will default to the `CONSUL_HTTP_TOKEN`
- environment variable if set.
+ not set here or on the Consul agent, it defaults to Consul's anonymous policy,
+ which may or may not allow writes. Defaults to the `CONSUL_HTTP_TOKEN`
+ environment variable if set. Nomad cannot refresh this token; if the token is
+ deleted, Nomad is not able to communicate with Consul.
- `verify_ssl` `(bool: true)`- Specifies if SSL peer verification should be used
when communicating to the Consul API client over HTTPS. Will default to the
@@ -334,6 +335,58 @@ consul {
}
```
+### Consul ACL policy for Nomad
+
+Nomad agents need access to Consul in order to register themselves in the
+service catalog and discover other Nomad agents via service discovery for
+automatic clustering. Nomad clients use Consul tokens from Workload Identity to
+register services and checks but need permissions on their own token to
+deregister. Nomad servers also create [configuration
+entries][consul_config_entry] for Consul Service Mesh, so the specific
+permissions vary slightly between Nomad servers and clients. The following
+Consul ACL policies represent the minimal permissions Nomad servers and clients
+need.
+
+
+
+
+```hcl
+agent_prefix "" {
+ policy = "read"
+}
+
+node_prefix "" {
+ policy = "write"
+}
+
+service_prefix "" {
+ policy = "write"
+}
+
+acl = "write"
+mesh = "write"
+```
+
+
+
+
+```hcl
+agent_prefix "" {
+ policy = "read"
+}
+
+node_prefix "" {
+ policy = "write"
+}
+
+service_prefix "" {
+ policy = "write"
+}
+```
+
+
+
+
### Consul Namespace
Consul does not allow ACL policies associated with namespaces to use agent
@@ -383,3 +436,4 @@ namespace "nomad-ns" {
[taskuser]: /nomad/docs/job-specification/task#user "Nomad task Block"
[consul_bound_aud]: /consul/docs/security/acl/auth-methods/jwt#boundaudiences
[`consul.namespace`]: /nomad/docs/job-specification/consul#namespace
+[consul_config_entry]: /consul/docs/connect/config-entries
diff --git a/website/content/docs/integrations/consul/acl.mdx b/website/content/docs/integrations/consul/acl.mdx
index 9499fe7fe2a..c17a19c01c4 100644
--- a/website/content/docs/integrations/consul/acl.mdx
+++ b/website/content/docs/integrations/consul/acl.mdx
@@ -18,7 +18,9 @@ running in Nomad.
Nomad agents need access to Consul in order to register themselves in the
service catalog and discover other Nomad agents via service discovery for
-automatic clustering. Nomad servers also create [configuration
+automatic clustering. Nomad clients use Consul tokens from Workload Identity to
+register services and checks but need permissions on their own token to
+deregister. Nomad servers also create [configuration
entries][consul_config_entry] for Consul Service Mesh, so the specific
permissions vary slightly between Nomad servers and clients. The following
Consul ACL policies represent the minimal permissions Nomad servers and clients
@@ -106,6 +108,9 @@ URL][nomad_jwks_url]. Consul servers call this URL to retrieve the public keys
Nomad uses to sign workload identities. With these keys, Consul is able to
validate their origin and confirm that they were actually created by Nomad.
+Nomad cannot recreate Consul tokens that have been deleted. The auth method
+configuration should never set the `MaxTokenTTL` field.
+
```json