From 1ec836f6fef3b263c5208718986e5f9c66d1793f Mon Sep 17 00:00:00 2001
From: Blake Covarrubias <blake@covarrubi.as>
Date: Sun, 8 May 2022 13:44:50 -0700
Subject: [PATCH 1/5] docs: Fix JSON formatted example ACL policies

Commit 9333fad added JSON formatted examples for all ACL polices.
Most of these these examples are not valid JSON, and thus an error is
raised when attempting to create the example policies/rules in Consul.

This commit fixes the example JSON formatted ACL rules so that they
are valid JSON. This enables readers to use the policies as-is from
the documentation to successfully create policies in Consul.

It also removes unnecessary arrays from the example policies so that
the policies are easier for practitioners to read and write.
---
 .../docs/security/acl/acl-policies.mdx        | 114 +++--
 .../content/docs/security/acl/acl-rules.mdx   | 465 ++++++++----------
 2 files changed, 272 insertions(+), 307 deletions(-)

diff --git a/website/content/docs/security/acl/acl-policies.mdx b/website/content/docs/security/acl/acl-policies.mdx
index bafa404d42..f97d8dcc17 100644
--- a/website/content/docs/security/acl/acl-policies.mdx
+++ b/website/content/docs/security/acl/acl-policies.mdx
@@ -32,13 +32,15 @@ A rule is composed of a resource declaration and an access level defined with th
 ```hcl
 <resource> {
   policy = "<policy disposition>"
-  }
+}
 ```
 
 ```json
-"<resource>": [{
-  "policy": "<policy disposition>"
-  }]
+{
+  "<resource>": {
+    "policy": "<policy disposition>"
+  }
+}
 ```
 
 </CodeTabs>
@@ -60,11 +62,13 @@ The following syntax describes how to include a resource label in the rule:
 ```
 
 ```json
-"<resource>": [{
-  "<label>": [{
-    "policy": "<policy disposition>"
-  }]
-}]
+{
+  "<resource>": {
+    "<label>": {
+      "policy": "<policy disposition>"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -85,7 +89,9 @@ Use the following syntax to create rules for these resources:
 ```
 
 ```json
-"<resource>": "<policy disposition>"
+{
+  "<resource>": "<policy disposition>"
+}
 ```
 
 </CodeTabs>
@@ -115,11 +121,13 @@ service "web-prod" {
 ```
 
 ```json
-"service": [{
-  "web-prod" : [{
-    "policy" : "deny"
-  }]
-}]
+{
+  "service": {
+    "web-prod": {
+      "policy": "deny"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -135,11 +143,13 @@ service_prefix "web" {
 ```
 
 ```json
-"service_prefix": [{
-  "web" : [{
-    "policy" : "write"
-  }]
-}]
+{
+  "service_prefix": {
+    "web": {
+      "policy": "write"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -155,11 +165,13 @@ service_prefix "" {
 ```
 
 ```json
-"service_prefix" : [{
-  "" : [{
-  "policy" :"read"
-  }]
-}]
+{
+  "service_prefix": {
+    "": {
+      "policy":"read"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -209,38 +221,22 @@ operator = "read"
 
 ```json
 {
-  "key": [
-    {
-      "foo/bar/secret": [
-        {
-          "policy": "deny"
-        }
-      ]
-    }
-  ],
-  "key_prefix": [
-    {
-      "": [
-        {
-          "policy": "read"
-        }
-      ]
+  "key_prefix": {
+    "": {
+      "policy": "read"
     },
-    {
-      "foo/": [
-        {
-          "policy": "write"
-        }
-      ]
+    "foo/": {
+      "policy": "write"
     },
-    {
-      "foo/private/": [
-        {
-          "policy": "deny"
-        }
-      ]
+    "foo/private/": {
+      "policy": "deny"
     }
-  ],
+  },
+  "key": {
+    "foo/bar/secret": {
+      "policy": "deny"
+    }
+  },
   "operator": "read"
 }
 ```
@@ -482,6 +478,11 @@ session_prefix "" {
 
 ```json
 {
+  "agent_prefix": {
+    "": {
+      "policy": "read"
+    }
+  },
   "key_prefix": {
     "vault/": {
       "policy": "write"
@@ -492,11 +493,6 @@ session_prefix "" {
       "policy": "write"
     }
   },
-  "agent_prefix": {
-    "": {
-      "policy": "read"
-    }
-  },
   "session_prefix": {
     "": {
       "policy": "write"
diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx
index 58ad1c610b..23131776a3 100644
--- a/website/content/docs/security/acl/acl-rules.mdx
+++ b/website/content/docs/security/acl/acl-rules.mdx
@@ -56,7 +56,9 @@ acl = "write"
 ```
 
 ```json
-"acl" : "write"
+{
+  "acl": "write"
+}
 ```
 
 </CodeTabs>
@@ -77,91 +79,64 @@ partition "example" {
   node "my-node" {
     policy = "write"
   }
-    ...
   namespace "ex-namespace" {
-    ...
+    policy = "write"
   }
   namespace_prefix "exns-" {
-    ...
+    policy = "write"
   }
 }
-partition_prefix "ex-" {
-  ... (Same as above)
+
+partition_prefix "example-" {
+  mesh = "read"
+
+  node "my-node" {
+    policy = "read"
+  }
+
+  namespace "ex-namespace" {
+    policy = "read"
+  }
 }
 ```
 
 ```json
 {
-  "partition": [
-    {
-      "example": [
-        {
-          "mesh": "write",
-          "node": [
-            {
-              "my-node": [
-                {
-                  "policy": "write"
-                }
-              ],
-              "namespace": [
-                {
-                  "ex-namespace": [
-                    {
-                      "policy": "read"
-                    }
-                  ]
-                }
-              ],
-              "namespace_prefix": [
-                {
-                  "exns-": [
-                    {
-                      "policy": "read"
-                    }
-                  ]
-                }
-              ]
-            }
-          ]
+  "partition": {
+    "example": {
+      "mesh": "write",
+      "node": {
+        "my-node": {
+          "policy": "write"
         }
-      ]
+      },
+      "namespace": {
+        "ex-namespace": {
+          "policy": "write"
+        }
+      },
+      "namespace_prefix": {
+        "exns-": {
+          "policy": "write"
+        }
+      }
     }
-  ]
-},
-{
-  "partition_prefix": [
-    {
-      "": [
-        {
+  },
+  "partition_prefix": {
+    "example-": {
+      "mesh": "read",
+      "node": {
+        "my-node": {
           "policy": "read"
         }
-      ],
-      "example": [
-        {
-          "mesh": "read",
-          "node": [
-            {
-              "my-node": [
-                {
-                  "policy": "read"
-                }
-              ]
-            }
-          ],
-          "namespace": [
-            {
-              "ex-namespace": [
-                {
-                  "policy": "read"
-                }
-              ]
-            }
-          ]
+      },
+      "namespace": {
+        "ex-namespace": {
+          "policy": "read"
         }
-      ]
+      }
     }
-  ]
+  }
 }
 ```
 
@@ -176,31 +151,33 @@ and [`service` or `service_prefix`](#service-rules) policies instead.
 <CodeTabs heading="Example agent rules">
 
 ```hcl
-agent_prefix "" {
-  policy = "read"
-}
 agent "foo" {
   policy = "write"
 }
+agent_prefix "" {
+  policy = "read"
+}
 agent_prefix "bar" {
   policy = "deny"
 }
 ```
 
 ```json
-"agent_prefix" : [{
-  "" : [{
-    "policy" : "read"
-    }],
-  "bar" : [{
-    "policy" : "deny"
-    }]
-  }],
-"agent" : [{
-  "foo" : [{
-    "policy" : "write"
-  }]
-}]
+{
+  "agent": {
+    "foo": {
+      "policy": "write"
+    }
+  },
+  "agent_prefix": {
+    "": {
+      "policy": "read"
+    },
+    "bar": {
+      "policy": "deny"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -232,16 +209,18 @@ event "deploy" {
 ```
 
 ```json
-"event_prefix" : [{
-  "" : [{
-    "policy" : "read"
-  }]
-}],
-"event" : [{
-  "deploy" : [{
-    "policy" : "write"
-  }]
-}]
+{
+  "event_prefix": {
+    "": {
+      "policy": "read"
+    }
+  },
+  "event": {
+    "deploy": {
+      "policy": "write"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -273,19 +252,21 @@ key "bar" {
 ```
 
 ```json
-"key_prefix" : [{
-  "" : [{
-    "policy" : "read"
-  }]
-}],
-"key" : [{
-  "foo" : [{
-    "policy" : "write"
-  }],
-  "bar" : [{
-    "policy" : "deny"
-  }]
-}]
+{
+  "key_prefix": {
+    "": {
+      "policy": "read"
+    }
+  },
+  "key": {
+    "foo": {
+      "policy": "write"
+    },
+    "bar": {
+      "policy": "deny"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -314,17 +295,19 @@ key_prefix "baz" {
 ```
 
 ```json
-"key_prefix" : [{
-  "" : [{
-    "policy" : "deny"
-  }],
-  "bar" : [{
-    "policy" : "list"
-  }],
-  "baz" : [{
-    "policy" : "read"
-  }]
-}]
+{
+  "key_prefix": {
+    "": {
+      "policy": "deny"
+    },
+    "bar": {
+      "policy": "list"
+    },
+    "baz": {
+      "policy": "read"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -364,7 +347,9 @@ keyring = "write"
 ```
 
 ```json
-"keyring" : "write"
+{
+  "keyring": "write"
+}
 ```
 
 </CodeTabs>
@@ -380,7 +365,9 @@ mesh = "write"
 ```
 
 ```json
-"mesh" : "write"
+{
+  "mesh": "write"
+}
 ```
 
 </CodeTabs>
@@ -399,6 +386,8 @@ The following examples describe how namespace rules can be defined in a policy:
 
 ```hcl
 namespace_prefix "" {
+  # grants permission to create and edit all namespaces
+  policy = "write"
 
   # grant service:read for all services in all namespaces
   service_prefix "" {
@@ -409,8 +398,6 @@ namespace_prefix "" {
   node_prefix "" {
     policy = "read"
   }
-  # grants permission to create and edit all namespace
-   policy = "write"
 }
 
 namespace "foo" {
@@ -444,79 +431,47 @@ namespace "foo" {
 
 ```json
 {
-  "namespace": [
-    {
-      "foo": [
-        {
-          "acl": "write",
-          "key_prefix": [
-            {
-              "": [
-                {
-                  "policy": "write"
-                }
-              ]
-            }
-          ],
-          "node_prefix": [
-            {
-              "": [
-                {
-                  "policy": "read"
-                }
-              ]
-            }
-          ],
-          "policy": "write",
-          "service_prefix": [
-            {
-              "": [
-                {
-                  "policy": "write"
-                }
-              ]
-            }
-          ],
-          "session_prefix": [
-            {
-              "": [
-                {
-                  "policy": "write"
-                }
-              ]
-            }
-          ]
+  "namespace_prefix": {
+    "": {
+      "policy": "write",
+      "service_prefix": {
+        "": {
+          "policy": "read"
         }
-      ]
-    }
-  ],
-  "namespace_prefix": [
-    {
-      "": [
-        {
-          "node_prefix": [
-            {
-              "": [
-                {
-                  "policy": "read"
-                }
-              ]
-            }
-          ],
-          "policy": "write",
-          "service_prefix": [
-            {
-              "": [
-                {
-                  "policy": "read"
-                }
-              ]
-            }
-          ]
+      },
+      "node_prefix": {
+        "": {
+          "policy": "read"
         }
-      ]
+      }
     }
-  ]
+  },
+  "namespace": {
+    "foo": {
+      "acl": "write",
+      "policy": "write",
+      "key_prefix": {
+        "": {
+          "policy": "write"
+        }
+      },
+      "session_prefix": {
+        "": {
+          "policy": "write"
+        }
+      },
+      "service_prefix": {
+        "": {
+          "policy": "write"
+        }
+      },
+      "node_prefix": {
+        "": {
+          "policy": "read"
+        }
+      }
+    }
+  }
 }
 ```
 
@@ -571,17 +526,21 @@ node "admin" {
 ```
 
 ```json
-"node_prefix" : [{
-  "" : [{
-    "policy" : "read"
-  }],
-  "app" : [{
-    "policy" : "write"
-  }],
-  "admin" : [{
-    "policy" : "deny"
-  }]
-}]
+{
+  "node_prefix": {
+    "": {
+      "policy": "read"
+    },
+  },
+  "node": {
+    "app": {
+      "policy": "write"
+    },
+    "admin": {
+      "policy": "deny"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -621,7 +580,9 @@ operator = "read"
 ```
 
 ```json
-"operator" : "read"
+{
+  "operator": "read"
+}
 ```
 
 </CodeTabs>
@@ -645,16 +606,18 @@ query "foo" {
 ```
 
 ```json
-"query_prefix" : [{
-  "" : [{
-    "policy" : "read"
-  }]
-}],
-"query" : [{
-  "foo" : [{
-    "policy" : "write"
-  }]
-}]
+{
+  "query_prefix": {
+    "": {
+      "policy": "read"
+    }
+  },
+  "query": {
+    "foo": {
+      "policy": "write"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -752,19 +715,21 @@ service "admin" {
 ```
 
 ```json
-"service_prefix" : [{
-  "" : [{
-    "policy" : "read"
-  }]
-}],
-"service" : [{
-  "app" : [{
-    "policy" : "write"
-  }],
-  "admin" : [{
-    "policy" : "deny"
-  }]
-}]
+{
+  "service_prefix": {
+    "": {
+      "policy": "read"
+    }
+  },
+  "service": {
+    "app": {
+      "policy": "write"
+    },
+    "admin": {
+      "policy": "deny"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -815,12 +780,14 @@ service "app" {
 ```
 
 ```json
-"service" : [{
-  "app" : [{
-    "policy" : "write"
-  }],
-  "intentions" : "read"
-}]
+{
+  "service": {
+    "app": {
+      "policy": "write",
+      "intentions": "read"
+    }
+  }
+}
 ```
 
 </CodeTabs>
@@ -851,19 +818,21 @@ session "admin" {
 ```
 
 ```json
-"session_prefix" : [{
-  "" : [{
-    "policy" : "read"
-  }]
-}],
-"session" : [{
-  "app" : [{
-    "policy" : "write"
-  }],
-  "admin" : [{
-    "policy" : "deny"
-  }]
-}]
+{
+  "session_prefix": {
+    "": {
+      "policy": "read"
+    }
+  },
+  "session": {
+    "app": {
+      "policy": "write"
+    },
+    "admin": {
+      "policy": "deny"
+    }
+  }
+}
 ```
 
 </CodeTabs>

From ddc09b661c124c80296c85dd0d83508e6797a476 Mon Sep 17 00:00:00 2001
From: Blake Covarrubias <blake@covarrubi.as>
Date: Mon, 9 May 2022 00:33:58 -0700
Subject: [PATCH 2/5] Remove HCL examples of roles since only JSON payloads can
 be used

---
 .../content/docs/security/acl/acl-roles.mdx   | 71 +------------------
 1 file changed, 1 insertion(+), 70 deletions(-)

diff --git a/website/content/docs/security/acl/acl-roles.mdx b/website/content/docs/security/acl/acl-roles.mdx
index 1421472c13..ded89f2d38 100644
--- a/website/content/docs/security/acl/acl-roles.mdx
+++ b/website/content/docs/security/acl/acl-roles.mdx
@@ -79,8 +79,6 @@ Service identities are used during the authorization process to automatically ge
 
 Use the following syntax to define a service identity:
 
-<CodeTabs>
-
 ```json
 {
   "ServiceIdentities": [
@@ -92,16 +90,6 @@ Use the following syntax to define a service identity:
 }
 ```
 
-
-```hcl
-"ServiceIdentities" = {
-  "ServiceName" = "<service name>"
-  "Datacenters" = ["<datacenter name>"]
-}
-```
-
-</CodeTabs>
-
 - `ServiceIdentities`: Declares a service identity block.
 - `ServiceIdentities.ServiceName`: String value that specifies the name of the service you want to associate with the policy.
 - `ServiceIdentities.Datacenters`: Array that specifies the names of datacenters in which the service identity applies. This field is optional.
@@ -136,28 +124,6 @@ Refer to the [rules reference](/docs/security/acl/acl-rules) for information abo
 
 The following role configuration contains service identities for the `web` and `db` services. Note that the `db` service is also scoped to the `dc1` datacenter so that the policy will only be applied to instances of `db` in `dc1`.
 
-<CodeTabs>
-<CodeBlockConfig filename="example-role.hcl">
-
-```hcl
-Description = "Showcases all input parameters"
-Name = "example-role"
-Policies = {
-  ID = "783beef3-783f-f41f-7422-7087dc272765"
-}
-Policies = {
-  Name = "node-read"
-}
-ServiceIdentities = {
-  ServiceName = "web"
-}
-ServiceIdentities = {
-  Datacenters = ["dc1"]
-  ServiceName = "db"
-}
-```
-
-</CodeBlockConfig>
 <CodeBlockConfig filename="example-role.json">
 
 ```json
@@ -191,7 +157,6 @@ ServiceIdentities = {
 ```
 
 </CodeBlockConfig>
-</CodeTabs>
 
 During the authorization process, the following policies for the `web` and `db` services will be generated and linked to the token:
 
@@ -243,9 +208,7 @@ node_prefix "" {
 
 ## Node Identities
 
-<!-- -> Added in Consul 1.8.1 -- remove and lean on doc version? -->
-
-You can specify a node identity when configuring roles or linking tokens to policies. _Node_ commonly refers to a Consul agent, but a node can also be a physical server, cloud instance, virtual machine, or container. 
+You can specify a node identity when configuring roles or linking tokens to policies. _Node_ commonly refers to a Consul agent, but a node can also be a physical server, cloud instance, virtual machine, or container.
 
 Node identities enable you to quickly construct policies for nodes, rather than manually creating identical polices for each node. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent.
 
@@ -253,8 +216,6 @@ Node identities enable you to quickly construct policies for nodes, rather than
 
 Use the following syntax to define a node identity:
 
-<CodeTabs>
-
 ```json
 {
   "NodeIdentities": [
@@ -266,16 +227,6 @@ Use the following syntax to define a node identity:
 }
 ```
 
-
-```hcl
-NodeIdentities = {
-  NodeName = "<node name>"
-  Datacenter = "<datacenter name>"
-}
-```
-
-</CodeTabs>
-
 - `NodeIdentities`: Declares a node identity block.
 - `NodeIdentities.NodeName`: String value that specifies the name of the node you want to associate with the policy.
 - `NodeIdentities.Datacenter`: String value that specifies the name of the datacenter in which the node identity applies.
@@ -306,25 +257,6 @@ Refer to the [rules reference](/docs/security/acl/acl-rules) for information abo
 
 The following role configuration contains a node identity for `node-1`. Note that the node identity is also scoped to the `dc2` datacenter. As a result, the policy will only be applied to nodes named `node-1` in `dc2`.
 
-<CodeTabs>
-<CodeBlockConfig filename="example-role.hcl">
-
-```hcl
-Description = "Showcases all input parameters"
-Name = "example-role"
-NodeIdentities = {
-  Datacenter = "dc2"
-  NodeName = "node-1",
-}
-Policies = {
-  ID = "783beef3-783f-f41f-7422-7087dc272765"
-}
-Policies = {
-  Name = "node-read"
-}
-```
-
-</CodeBlockConfig>
 <CodeBlockConfig filename="example-role.json">
 
 ```json
@@ -349,7 +281,6 @@ Policies = {
 ```
 
 </CodeBlockConfig>
-</CodeTabs>
 
 During the authorization process, the following policy will be generated and linked to the token:
 

From ab9c7d2dd4c7dcb36adc9a5ad4adbe2f8504918e Mon Sep 17 00:00:00 2001
From: Blake Covarrubias <blake@covarrubi.as>
Date: Sun, 8 May 2022 17:48:37 -0700
Subject: [PATCH 3/5] Remove unnecessary quotes from HCL variables

---
 website/content/docs/discovery/checks.mdx     | 36 +++++++++----------
 .../docs/security/acl/acl-policies.mdx        |  8 ++---
 .../content/docs/security/acl/acl-tokens.mdx  | 14 ++++----
 3 files changed, 29 insertions(+), 29 deletions(-)

diff --git a/website/content/docs/discovery/checks.mdx b/website/content/docs/discovery/checks.mdx
index 401f447c67..20aba4b9a7 100644
--- a/website/content/docs/discovery/checks.mdx
+++ b/website/content/docs/discovery/checks.mdx
@@ -151,7 +151,7 @@ A script check:
 ```hcl
 check = {
   id = "mem-util"
-  name =  "Memory utilization"
+  name = "Memory utilization"
   args = ["/usr/local/bin/check_mem.py", "-limit", "256MB"]
   interval = "10s"
   timeout = "1s"
@@ -186,12 +186,12 @@ check = {
   tls_skip_verify = false
   method = "POST"
   header = {
-     Content-Type =  ["application/json"]
+     Content-Type = ["application/json"]
   }
   body = "{\"method\":\"health\"}"
   disable_redirects = true
-  interval =  "10s"
-  timeout =  "1s"
+  interval = "10s"
+  timeout = "1s"
 }
 ```
 
@@ -248,11 +248,11 @@ A TTL check:
 <CodeTabs heading="TTL Check">
 
 ```hcl
-check =  {
+check = {
   id = "web-app"
   name = "Web App Status"
   notes = "Web app does a curl internally every 10 seconds"
-  ttl =  "30s"
+  ttl = "30s"
 }
 ```
 
@@ -305,11 +305,11 @@ A gRPC check for the whole application:
 
 ```hcl
 check = {
-  id =  "mem-util"
+  id = "mem-util"
   name = "Service health status"
-  grpc =  "127.0.0.1:12345"
+  grpc = "127.0.0.1:12345"
   grpc_use_tls = true
-  interval =  "10s"
+  interval = "10s"
 }
 ```
 
@@ -482,11 +482,11 @@ health check definition, like so:
 <CodeTabs heading="Status Field Example">
 
 ```hcl
-check =  {
-  "id": "mem",
-  "args": ["/bin/check_mem", "-limit", "256MB"]
-  "interval": "10s"
-  "status": "passing"
+check = {
+  id = "mem"
+  args = ["/bin/check_mem", "-limit", "256MB"]
+  interval = "10s"
+  status = "passing"
 }
 ```
 
@@ -516,10 +516,10 @@ provided by adding a `service_id` field to a check configuration:
 <CodeTabs heading="Status Field Example">
 
 ```hcl
-check =  {
+check = {
   id = "web-app"
-  name =  "Web App Status"
-  service_id =  "web-app"
+  name = "Web App Status"
+  service_id = "web-app"
   ttl = "30s"
 }
 ```
@@ -635,7 +635,7 @@ checks = [
     name = "HTTP TCP on port 80"
     tcp = "localhost:80"
     interval = "10s"
-    timeout =  "1s"
+    timeout  = "1s"
     success_before_passing =  3
     failures_before_warning =  1
     failures_before_critical =  3
diff --git a/website/content/docs/security/acl/acl-policies.mdx b/website/content/docs/security/acl/acl-policies.mdx
index f97d8dcc17..7c5286e0bb 100644
--- a/website/content/docs/security/acl/acl-policies.mdx
+++ b/website/content/docs/security/acl/acl-policies.mdx
@@ -460,19 +460,19 @@ In the following example, Vault is registered as a service and provided access t
 ```hcl
 # Provide KV visibility to all agents.
 agent_prefix "" {
-  "policy" = "read"
+  policy = "read"
 }
 # Enable resources prefixed with 'vault/' to write to the KV
 key_prefix "vault/" {
-  "policy" = "write"
+  policy = "write"
 }
 # Enable the vault service to write to the KV
 service "vault" {
-  "policy" = "write"
+  policy = "write"
 }
 # Enable the agent to initialize a new session.
 session_prefix "" {
-  "policy" = "write"
+  policy = "write"
 }
 ```
 
diff --git a/website/content/docs/security/acl/acl-tokens.mdx b/website/content/docs/security/acl/acl-tokens.mdx
index fcb0abe575..1267aafbf4 100644
--- a/website/content/docs/security/acl/acl-tokens.mdx
+++ b/website/content/docs/security/acl/acl-tokens.mdx
@@ -38,12 +38,12 @@ Specify the value of the `SecretID` attribute with the `token` parameter when co
 <CodeBlockConfig lineNumbers highlight="6">
 
 ```hcl
-"service" = {
-  "id" = "redis"
-  "name" = "redis"
+service = {
+  id = "redis"
+  name = "redis"
   ...
-  "namespace" = "foo"
-  "token" = "233b604b-b92e-48c8-a253-5f11514e4b50"
+  namespace = "foo"
+  token = "233b604b-b92e-48c8-a253-5f11514e4b50"
 }
 ```
 
@@ -86,8 +86,8 @@ In the following example, the agent is configured to use a default token:
 <CodeTabs>
 
 ```hcl
-"tokens" = {
-  "default" = "233b604b-b92e-48c8-a253-5f11514e4b50"
+tokens = {
+  default = "233b604b-b92e-48c8-a253-5f11514e4b50"
 }
 ```
 

From 34b2f5daea2c6098022cec14e7db2371157121ae Mon Sep 17 00:00:00 2001
From: Blake Covarrubias <blake@covarrubi.as>
Date: Sun, 8 May 2022 23:25:01 -0700
Subject: [PATCH 4/5] Clarify purpose of example ACL rules and policies

---
 .../docs/security/acl/acl-policies.mdx        |  3 +-
 .../content/docs/security/acl/acl-rules.mdx   | 33 +++++++++++++------
 .../content/docs/security/acl/acl-tokens.mdx  | 28 +++++++---------
 website/content/docs/security/acl/index.mdx   |  6 ++--
 4 files changed, 39 insertions(+), 31 deletions(-)

diff --git a/website/content/docs/security/acl/acl-policies.mdx b/website/content/docs/security/acl/acl-policies.mdx
index 7c5286e0bb..5a1b2f8d30 100644
--- a/website/content/docs/security/acl/acl-policies.mdx
+++ b/website/content/docs/security/acl/acl-policies.mdx
@@ -453,7 +453,8 @@ service "consul-snapshot" {
 
 If you are using [Vault](https://www.vaultproject.io/docs) to manage secrets in your infrastructure, you can configure Vault to use Consul's key/value (KV) store as backend storage to persist Vault's data. Refer to the [Consul KV documentation](/docs/dynamic-app-config/kv) and the [Vault storage documentation](https://www.vaultproject.io/docs/configuration/storage) for additional information.
 
-In the following example, Vault is registered as a service and provided access to Consul's KV store.
+In the following example, the ACL policy enables Vault to register as a service
+and provides access to the `vault/` path in Consul's KV store.
 
 <CodeTabs>
 
diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx
index 23131776a3..3234c9cd0d 100644
--- a/website/content/docs/security/acl/acl-rules.mdx
+++ b/website/content/docs/security/acl/acl-rules.mdx
@@ -47,7 +47,8 @@ The `acl = "write"` rule is also required to create snapshots. This is because a
 
 Rules for ACL resources do not use labels.
 
-In the following example, `write` access to the ACL API. The rule enables the operator to read or write ACLs, as well as discover the secret ID of any token.
+In the following example, the `acl` rule is configured with `write` access to the ACL API.
+The rule enables the operator to read or write ACLs, as well as discover the secret ID of any token.
 
 <CodeTabs heading="Example acl rule">
 
@@ -68,8 +69,15 @@ acl = "write"
 The `partition` and `partition_prefix` resource controls access to one or more admin partitions.
 You can include any number of namespace rules inside the admin partition.
 
-In the following example, the agent has write access to the `ex-namespace` namespace, as well as namespaces prefixed with `ex-` in the `example` partition.
-The `mesh` resource is also scoped to the admin partition rule, which grants `write` access to mesh-level resources in the partition:
+In the following example, the policy grants `write` access to the `ex-namespace`
+namespace, as well as namespaces prefixed with `exns-` in the `example` partition.
+The `mesh` resource is also scoped to the admin partition rule, which grants
+`write` access to mesh-level resources in the `example` partition.
+
+In addition, the policy grants `read` access to the `ex-namespace` namespace, as
+well as namespaces prefixed with `exns-` in all partitions containing the
+`example-` prefix. Read access is granted for `mesh` resource scoped within the
+associated partition.
 
 <CodeTabs heading="Example admin partition rules">
 
@@ -183,9 +191,9 @@ agent_prefix "bar" {
 </CodeTabs>
 
 Agent rules are keyed by the node name they apply to. In the example above the rules
-allow read-only access to any node name by using the empty prefix, read-write access to
-the node with the _exact_ name `foo`, and denies all access to any node name that starts
-with `bar`.
+allow read-write access to the node with the _exact_ name `foo`, read-only access
+to any node name by using the empty prefix, and denies all access to any node
+name that starts with `bar`.
 
 Since [Agent API](/api-docs/agent) utility operations may be required before an agent is joined to
 a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be
@@ -276,7 +284,12 @@ to any key name with the empty prefix rule, allow read-write access to the "foo"
 
 ### List Policy for Keys
 
-Enable the `list` policy disposition (Consul 1.0+) by setting the `acl.enable_key_list_policy` parameter to `true`. The disposition provides recursive access to `key` entries. Refer to the [KV API](/api-docs/kv#recurse) documentation for additional information. In the following example, `key` resources that start with `bar` are listed.
+Enable the `list` policy disposition (Consul 1.0+) by setting the
+`acl.enable_key_list_policy` parameter to `true`. The disposition provides
+recursive access to `key` entries. Refer to the [KV API](/api-docs/kv#recurse)
+documentation for additional information.
+
+In the following example, `key` resources that start with `bar` may be listed.
 
 <CodeTabs heading="Example 'key' rules">
 
@@ -563,7 +576,7 @@ These actions may required an ACL token to complete. Use the following methods t
 * Provide an ACL token with `service` and `check` definitions at registration time.
   This allows for greater flexibility and enables the use of multiple tokens on the same agent.
   Refer to the [services](/docs/agent/services) and [checks](/docs/agent/checks) documentation for examples.
-  Tokens may also be passed to the [HTTP API](/api) for operations that require them.
+  Tokens may also be passed to the [HTTP API](/api-docs) for operations that require them.
 
 ## Operator Rules
 
@@ -755,10 +768,10 @@ to use for registration events:
    tokens on the same agent. Examples of what this looks like are available for
    both [services](/docs/discovery/services) and
    [checks](/docs/discovery/checks). Tokens may also be passed to the [HTTP
-   API](/api) for operations that require them. **Note:** all tokens
+   API](/api-docs) for operations that require them. **Note:** all tokens
    passed to an agent are persisted on local disk to allow recovery from
    restarts. See [`-data-dir` flag
-   documentation](/docs/agent/config/config-files#acl_token) for notes on securing
+   documentation](/docs/agent/config/cli-flags#_data_dir) for notes on securing
    access.
 
 In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with
diff --git a/website/content/docs/security/acl/acl-tokens.mdx b/website/content/docs/security/acl/acl-tokens.mdx
index 1267aafbf4..8c80be719d 100644
--- a/website/content/docs/security/acl/acl-tokens.mdx
+++ b/website/content/docs/security/acl/acl-tokens.mdx
@@ -120,7 +120,7 @@ You can export tokens to environment variables on the local machine, which enabl
 
 ### API Requests
 
-Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/api-docs/index#authentication) for details.
+Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/api-docs#authentication) for details.
 
 The following example shows the header for a GET request to the `agent/members` endpoint.
 
@@ -137,12 +137,12 @@ Refer to the [API](/api-docs/acl/token) or [command line](/commands/acl/token) d
 | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- |
 | `AccessorID`        | Used for [audit logging](/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID.                                                                                         | String    | auto-generated |
 | `SecretID`          | Used to request access to resources, data, and APIs.                                                                                                                                                                                                       | String    | auto-generated |
-| `Partition`         | <EnterpriseAlert inline/> Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information.                                                                     | `default` |
+| `Partition`         | <EnterpriseAlert inline/> Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information.                                                                     | String    | `default`      |
 | `Namespace`         | <EnterpriseAlert inline/> Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/docs/enterprise/namespaces) for additional information.                                                                                | String    | `default`      |
 | `Description`       | Human-readable description for documenting the purpose of the token.                                                                                                                                                                                       | String    | none           |
 | `Local`             | Indicates whether the token should be replicated globally or local to the datacenter. <br/> Set to `false` to replicate globally across all reachable datacenters. <br/>Setting to `true` configures the token to functional in the local datacenter only. | Boolean   | `false`        |
-| `ServiceIdentities` | Specifies a list of nodes to apply to the token. See [Service Identities](/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information.                                                                                        | Array     | none           |
-| `NodeIdentities`    | Specifies a list of nodes to apply to the token. See [Node Identities](/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information.                                                                                             | Array     | none           |
+| `ServiceIdentities` | Specifies a list of service identities to apply to the token. See [Service Identities](/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information.                                                                   | Array     | none           |
+| `NodeIdentities`    | Specifies a list of node identities to apply to the token. See [Node Identities](/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information.                                                                            | Array     | none           |
 | `Legacy`            | Indicates if the token was created using the the legacy ACL system.                                                                                                                                                                                        | Boolean   | `false`        |
 | `Policies`          | List of policies linked to the token, including the policy ID and name.                                                                                                                                                                                    | String    | none           |
 
@@ -162,7 +162,7 @@ All reserved tokens except the `initial_management` token can be created or upda
 
 ### Snapshot Tokens
 
-Snapshots are artifacts created with the [snapshot API](/api-docs/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and require, and interacting with them requires a token with `write` privileges.
+Snapshots are artifacts created with the [snapshot API](/api-docs/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and interacting with them requires a token with `acl:write` privileges.
 
 ### ACL Agent Token
 
@@ -174,6 +174,8 @@ The [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) is a special toke
 
 Here's an example policy sufficient to accomplish the above for a node called `mynode`:
 
+<CodeBlockConfig heading="Example agent policy permitting internal operations">
+
 ```hcl
 node "mynode" {
   policy = "write"
@@ -186,19 +188,10 @@ key_prefix "_rexec" {
 }
 ```
 
+</CodeBlockConfig>
+
 The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted.
 
-<!-- Consider removing this content now that we have versioned docs
-
-In Consul 1.4 - 1.10, the following special tokens were known by different names:
-
-| New Name (1.11+)                                                                     | Old Name (1.4 - 1.10)                                                    |
-| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
-| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery)         | [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) |
-| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/options#acl_tokens_master)             |
-
--->
-
 ## Built-in Tokens
 
 Consul includes a built-in anonymous token and initial management token. Both tokens are injected during when you bootstrap the cluster.
@@ -215,7 +208,8 @@ The description and policies may be updated, but the anonymous token cannot be d
 
 ### Initial Management Token
 
-Including an initial management token in the Consul configuration creates the token and links it with the built-in global management policy.
+Including an initial management token in the Consul configuration creates the
+token and links it with the built-in [global management](/docs/security/acl/acl-policies#global-management) policy.
 The bearer will have have unrestricted privileges to resources and APIs.
 The `SecretID` attribute will be set to the value of the configuration entry.
 
diff --git a/website/content/docs/security/acl/index.mdx b/website/content/docs/security/acl/index.mdx
index 2b15986c80..acb519103a 100644
--- a/website/content/docs/security/acl/index.mdx
+++ b/website/content/docs/security/acl/index.mdx
@@ -69,7 +69,7 @@ Refer to the [Roles](/docs/security/acl/acl-roles) topic for additional informat
 
 ## Service Identities
 
-Service identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh.
+Service identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. They are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh.
 
 Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service.
 
@@ -80,9 +80,9 @@ Refer to the following topics for additional information about service identitie
 
 ## Node Identities
 
-Node identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent.
+Node identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent.
 
-Node identities enable you to quickly construct policies for nodes, rather than creating identical polices for each service.
+Node identities enable you to quickly construct policies for nodes, rather than creating identical polices for each node.
 
 Refer to the following topics for additional information about node identities:
 

From 21168aa6172b8c108c8bf035f18ffe0f85a20d80 Mon Sep 17 00:00:00 2001
From: Blake Covarrubias <blake@covarrubi.as>
Date: Mon, 9 May 2022 00:34:42 -0700
Subject: [PATCH 5/5] Redirect /api-docs/acl/acl to the new URL

---
 website/content/docs/security/acl/acl-policies.mdx | 2 +-
 website/content/docs/security/acl/acl-rules.mdx    | 2 +-
 website/redirects.js                               | 5 +++++
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/security/acl/acl-policies.mdx b/website/content/docs/security/acl/acl-policies.mdx
index 5a1b2f8d30..25af824c6d 100644
--- a/website/content/docs/security/acl/acl-policies.mdx
+++ b/website/content/docs/security/acl/acl-policies.mdx
@@ -279,7 +279,7 @@ You can can define several attributes that attach additional metadata and specif
 
 ### HTTP API Endpoint
 
-The endpoint takes data formatted in HCL or JSON. Refer to the [ACL HTTP API endpoint documentation](/api-docs/acl/acl) for details about the API.
+The endpoint takes data formatted in HCL or JSON. Refer to the [ACL HTTP API endpoint documentation](/api-docs/acl) for details about the API.
 
 The following example adds a set of rules to a policy called `my-app-policy`. The policy defines access to the `key` resource (Consul K/V). The rules are formatted in HCL, but they are wrapped in JSON so that the data can be sent using cURL:
 
diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx
index 3234c9cd0d..fc8806fd4b 100644
--- a/website/content/docs/security/acl/acl-rules.mdx
+++ b/website/content/docs/security/acl/acl-rules.mdx
@@ -15,7 +15,7 @@ The following table provides an overview of the resources you can use to create
 
 | Resource                           | Description                                                                                                                                                                                                                                                                                                                                          | Labels |
 | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
-| `acl`                              | Controls access to ACL operations in the [ACL API](/api-docs/acl/acl). <br/>See [ACL Resource Rules](#acl-resource-rules) for details.                                                                                                                                                                                                                    | No     |
+| `acl`                              | Controls access to ACL operations in the [ACL API](/api-docs/acl). <br/>See [ACL Resource Rules](#acl-resource-rules) for details.                                                                                                                                                                                                                   | No     |
 | `partition`<br/>`partition_prefix` | <EnterpriseAlert inline /> Controls access to one or more admin partitions. <br/>See [Admin Partition Rules](#admin-partition-rules) for details.                                                                                                                                                                                                    | Yes    |
 | `agent`<br/>`agent_prefix`         | Controls access to the utility operations in the [Agent API](/api-docs/agent), such as `join` and `leave`. <br/>See [Agent Rules](#agent-rules) for details.                                                                                                                                                                                              | Yes    |
 | `event`<br/>`event_prefix`         | Controls access to event operations in the [Event API](/api-docs/event), such as firing and listing events. <br/>See [Event Rules](#event-rules) for details.                                                                                                                                                                                             | Yes    |
diff --git a/website/redirects.js b/website/redirects.js
index 51dfb4b887..59be38aad1 100644
--- a/website/redirects.js
+++ b/website/redirects.js
@@ -76,6 +76,11 @@ module.exports = [
     destination: '/docs/security/acl/acl-legacy',
     permanent: true,
   },
+  {
+    source: '/api-docs/acl/acl',
+    destination: '/api-docs/acl',
+    permanent: true,
+  },
   {
     source: '/api-docs/acl-legacy',
     destination: '/api-docs/acl/legacy',