Merge e961d91 into backport/docs/pglass/NET-1825-acl-token-docs/optio…

…nally-dynamic-viper
hashicorp · Jun 14, 2023 · dee799a · dee799a
2 parents b70c00a + e961d91
commit dee799a
Show file tree

Hide file tree

Showing 5 changed files with 779 additions and 547 deletions.
diff --git a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx
@@ -27,16 +27,15 @@ The mesh gateway must present a token linked to a policy that grants the followi
 
 @include 'create-token-requirements.mdx'
 
-## Create a token linked to a policy
+
+## Consul OSS
 
 To create a token for the mesh gateway, you must define a policy, register the policy with Consul, and link the policy to a token.
 
 ### Define a custom policy
 
 You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
 
-#### Consul OSS
-
 The following example policy grants the mesh gateway the appropriate permissions for the mesh gateway to register as a service named `mesh-gateway`.
 
 <CodeTabs>
@@ -88,7 +87,93 @@ agent_prefix "" {
 </CodeTabs>
 
 
-#### Consul Enterprise using `default` partition
+### Register the policy with Consul
+
+After defining the policy, you can register the policy with Consul using the command line or API endpoint.
+
+The following commands create the ACL policy and token.
+
+<Tabs>
+
+<Tab heading="CLI" group="CLI">
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`:
+
+```shell-session
+$ consul acl policy create \
+    -name "mgw-register" -rules @mgw-register.hcl \
+    -description "Mesh gateway policy"
+```
+
+</Tab>
+
+<Tab heading="API" group="API">
+
+Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the custom policy defined in `mgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body.
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
+  –-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+  --data '{
+  "Name": "mgw-register",
+  "Description": "Mesh gateway policy",
+  "Rules": "mesh = \"write\"\npeering = \"read\"\nservice \"mesh-gateway\" {\n   policy = \"write\"\n}\nservice_prefix \"\" {\n   policy = \"read\"\n}\nnode_prefix \"\" {\n   policy = \"read\"\n}\nagent_prefix \"\" {\n   policy = \"read\"\n}\n"
+}'
+```
+
+Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
+
+</Tab>
+
+</Tabs>
+
+### Link the policy to a token
+
+After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.
+
+<Tabs>
+
+<Tab heading="CLI" group="CLI">
+
+Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
+
+The following command creates the ACL token linked to the policy `mgw-register`.
+
+```shell-session
+$ consul acl token create \
+    -description "Mesh gateway token" \
+    -policy-name "mgw-register"
+```
+
+</Tab>
+
+<Tab heading="API" group="API">
+
+Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
+  –-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+  --data '{
+  "Policies": [
+    {
+      "Name": "mgw-register"
+    }
+  ]
+}'
+```
+
+</Tab>
+
+</Tabs>
+
+## Consul Enterprise in default partition
+
+To create a token for the mesh gateway, you must define a policy, register the policy with Consul, and link the policy to a token.
+
+### Define a custom policy
+
+You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
 
 You can specify an admin partition and namespace when using Consul Enterprise. Mesh gateways must register into the `default` namespace. The following policy allows a mesh gateway to register as a service named `mesh-gateway` in the default partition.
 
@@ -161,7 +246,101 @@ namespace_prefix "" {
 </CodeTabs>
 
 
-#### Consul Enterprise using non-`default` partition
+### Register the policy with Consul
+
+After defining the policy, you can register the policy with Consul using the command line or API endpoint.
+
+The following commands create the ACL policy and token.
+
+<Tabs>
+
+<Tab heading="CLI" group="CLI">
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`:
+
+You can specify an admin partition when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition. You must create the policy in the partition where the mesh gateway registers. The following example creates the policy in the `default` partition.
+
+```shell-session
+$ consul acl policy create -partition "default" \
+  -name mgw-register -rules @mgw-register.hcl \
+  -description "Mesh gateway policy"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+</Tab>
+
+<Tab heading="API" group="API">
+
+Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the custom policy defined in `mgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body.
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
+  –-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+  --data '{
+  "Name": "mgw-register",
+  "Description": "Mesh gateway policy",
+  "Partition": "default",
+  "Rules": "mesh = \"write\"\npeering = \"read\"\npartition_prefix \"\" {\n  peering = \"read\"\n}\nnamespace \"default\" {\n  service \"mesh-gateway\" {\n     policy = \"write\"\n  }\n  agent_prefix \"\" {\n     policy = \"read\"\n  }\n}\nnamespace_prefix \"\" {\n  node_prefix \"\" {\n  \tpolicy = \"read\"\n  }\n  service_prefix \"\" {\n     policy = \"read\"\n  }\n}\n"
+}'
+```
+
+Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
+
+</Tab>
+
+</Tabs>
+
+### Link the policy to a token
+
+After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.
+
+<Tabs>
+
+<Tab heading="CLI" group="CLI">
+
+Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
+
+You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
+
+```shell-session
+$ consul acl token create -partition "default" \
+    -description "Mesh gateway token" \
+    -policy-name "mgw-register"
+```
+
+</Tab>
+
+<Tab heading="API" group="API">
+
+Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
+
+You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
+  –-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+  --data '{
+  "Policies": [
+    {
+      "Name": "mgw-register"
+    }
+  ],
+  "Partition": "default"
+}'
+```
+
+</Tab>
+
+</Tabs>
+
+## Consul Enterprise in non-default partition
+
+To create a token for the mesh gateway, you must define a policy, register the policy with Consul, and link the policy to a token.
+
+### Define a custom policy
+
+You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
 
 You can specify an admin partition and namespace when using Consul Enterprise. Mesh gateways must register into the `default` namespace. To register a mesh gateway in a non-default partition, create the ACL policy and token in the partition where the mesh gateway registers. The following ACL policy rules allow a mesh gateway to register as the `mesh-gateway` service in a non-default partition.
 
@@ -225,70 +404,33 @@ namespace_prefix "" {
 
 </CodeTabs>
 
-
 ### Register the policy with Consul
 
 After defining the policy, you can register the policy with Consul using the command line or API endpoint.
 
 The following commands create the ACL policy and token.
 
-#### CLI
-
-Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`:
+<Tabs>
 
-##### Consul OSS
+<Tab heading="CLI" group="CLI">
 
-```shell-session
-$ consul acl policy create \
-    -name "mgw-register" -rules @mgw-register.hcl \
-    -description "Mesh gateway policy"
-```
-
-##### Consul Enterprise
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`:
 
 You can specify an admin partition when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition. You must create the policy in the partition where the mesh gateway registers. The following example creates the policy in the partition `ptn1`.
 
 ```shell-session
-consul acl policy create \
+$ consul acl policy create -partition "ptn1" \
   -name mgw-register -rules @mgw-register.hcl \
-  -description "Mesh gateway policy" \
-  -partition ptn1
+  -description "Mesh gateway policy"
 ```
 
 Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
 
-#### API
-
-Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the custom policy defined in `mgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body.
-
-##### Consul OSS
-
-
-```shell-session
-$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
-  –-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
-  --data '{
-  "Name": "mgw-register",
-  "Description": "Mesh gateway policy",
-  "Rules": "mesh = \"write\"\npeering = \"read\"\nservice \"mesh-gateway\" {\n   policy = \"write\"\n}\nservice_prefix \"\" {\n   policy = \"read\"\n}\nnode_prefix \"\" {\n   policy = \"read\"\n}\nagent_prefix \"\" {\n   policy = \"read\"\n}\n"
-}'
-```
-
-##### Consul Enterprise (Default Partition)
-
+</Tab>
 
-```shell-session
-$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
-  –-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
-  --data '{
-  "Name": "mgw-register",
-  "Description": "Mesh gateway policy",
-  "Partition": "default",
-  "Rules": "mesh = \"write\"\npeering = \"read\"\npartition_prefix \"\" {\n  peering = \"read\"\n}\nnamespace \"default\" {\n  service \"mesh-gateway\" {\n     policy = \"write\"\n  }\n  agent_prefix \"\" {\n     policy = \"read\"\n  }\n}\nnamespace_prefix \"\" {\n  node_prefix \"\" {\n  \tpolicy = \"read\"\n  }\n  service_prefix \"\" {\n     policy = \"read\"\n  }\n}\n"
-}'
-```
+<Tab heading="API" group="API">
 
-##### Consul Enterprise (Non-default Partition)
+Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the custom policy defined in `mgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body.
 
 ```shell-session
 $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
@@ -303,54 +445,33 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
 
 Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
 
-### Link the policy to a token
-
-After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.
+</Tab>
 
-#### CLI
+</Tabs>
 
-Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
+### Link the policy to a token
 
-##### Consul OSS
+After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.
 
-The following command creates the ACL token linked to the policy `mgw-register`.
+<Tabs>
 
-```shell-session
-$ consul acl token create \
-    -description "Mesh gateway token" \
-    -policy-name "mgw-register"
-```
+<Tab heading="CLI" group="CLI">
 
-##### Consul Enterprise
+Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
 
 You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
 
 ```shell-session
-$ consul acl token create -partition ptn1 \
+$ consul acl token create -partition "ptn1" \
     -description "Mesh gateway token" \
     -policy-name "mgw-register"
 ```
 
-#### API
+</Tab>
 
-Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
+<Tab heading="API" group="API">
 
-##### Consul OSS
-
-
-```shell-session
-$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
-  –-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
-  --data '{
-  "Policies": [
-    {
-      "Name": "mgw-register"
-    }
-  ]
-}'
-```
-
-##### Consul Enterprise
+Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
 
 You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
 
@@ -367,4 +488,6 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
 }'
 ```
 
-@include 'create-token-auth-methods.mdx'
+</Tab>
+
+</Tabs>