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] 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>