NET-1825: New ACL token creation docs (#16465) (#17735)

Co-authored-by: Paul Glass <pglass@hashicorp.com>
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com>

website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx

@@ -0,0 +1,352 @@
+---
+layout: docs
+page_title: Create a token for terminating gateway registration
+description: >-
+  Learn how to create ACL tokens that your terminating gateway can present to Consul servers so that they can register with the Consul catalog.
+---
+
+# Create a terminating gateway token
+
+This topic describes how to create an ACL token that enables a terminating gateway to register with Consul.
+
+## Introduction
+
+Terminating gateways enable connectivity within your organizational network from services in the Consul service mesh to services and destinations outside the mesh.
+
+To learn how to configure terminating gateways, refer to the [Terminating Gateways](/consul/docs/connect/gateways/terminating-gateway#terminating-gateway-configuration) documentation and the [Understand Terminating Gateways](/consul/tutorials/developer-mesh/service-mesh-terminating-gateways) tutorial.
+
+## Requirements
+
+Core ACL functionality is available in all versions of Consul.
+
+The terminating gateway token must be linked to policies that grant the appropriate set of permissions in order to be discoverable and to forward traffic out of the mesh. The following permissions are required:
+
+* `service:write` to allow the terminating gateway to register into the catalog
+* `service:write` for each service that it forwards traffic for
+* `node:read` for the nodes of each service that it forwards traffic for
+* `service:read` for all services and `node:read` for all nodes in order to discover and route to services
+* `agent:read` to enable the `consul connect envoy` CLI command to automatically discover gRPC settings from the Consul agent. If this command is not used to start the gateway or if the Consul agent uses the default gRPC settings, then you can omit the `agent:read` permission.
+
+@include 'create-token-requirements.mdx'
+
+## Consul OSS
+
+To create a token for the terminating gateway, you must define a policy, register the policy with Consul, and link the policy to a token.
+
+### Define a policy
+
+You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
+
+The following example policy is defined in a file. The policy grants the appropriate permissions to register as a service named `terminating-gateway` and to operate as a terminating gateway. For this example, the terminating gateway forwards traffic for two services named `external-service-1` and `external-service-2`. The policy examples include `service:write` permissions for these services. If you have additional services, your policy must include `service:write` permissions for the additional services to be included in the policy rules.
+
+<CodeTabs>
+
+```hcl
+service "terminating-gateway" {
+   policy = "write"
+}
+service "external-service-1" {
+  policy = "write"
+}
+service "external-service-2" {
+  policy = "write"
+}
+node_prefix "" {
+  policy = "read"
+}
+agent_prefix "" {
+  policy = "read"
+}
+```
+
+```json
+{
+  "service": {
+    "terminating-gateway": [{
+      "policy": "write"
+    }],
+    "external-service-1": [{
+      "policy": "write"
+    }],
+    "external-service-2": [{
+      "policy": "write"
+    }]
+  },
+  "node_prefix": {
+    "": [{
+      "policy": "read"
+    }]
+  },
+  "agent_prefix": {
+    "": [{
+      "policy": "read"
+    }]
+  }
+}
+```
+
+</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.
+
+<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 policy defined in `tgw-register.hcl`:
+
+```shell-session
+$ consul acl policy create \
+    -name "tgw-register" -rules @tgw-register.hcl \
+    -description "Terminating 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 policy defined in `tgw-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": "tgw-register",
+  "Description": "Terminating gateway policy",
+  "Rules": "service \"terminating-gateway\" {\n   policy = \"write\"\n}\nservice \"external-service-1\" {\n  policy = \"write\"\n}\nservice \"external-service-2\" {\n  policy = \"write\"\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](/consul/docs/security/acl/auth-methods).
+
+<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 `tgw-register`.
+
+```shell-session
+$ consul acl token create \
+    -description "Terminating gateway token" \
+    -policy-name "tgw-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": "tgw-register"
+    }
+  ]
+}'
+```
+
+</Tab>
+
+</Tabs>
+
+## Consul Enterprise
+
+To create a token for the terminating gateway, you must define a policy, register the policy with Consul, and link the policy to a token.
+
+### Define a policy
+
+You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. 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 creating policies in Consul Enterprise. The policy is only valid in the specified scopes.
+
+The following example policy is defined in a file. The policy grants the appropriate permissions for a terminating gateway to register as a service named `terminating-gateway` in namespace `ns1` in partition `ptn1`.
+
+For this example, the terminating gateway forwards traffic for the following two services:
+
+* `external-service-1` in the `default` namespace
+* `external-service-2` in the `ns1` namespace
+
+The policy examples include `service:write` permissions for these services. If you have additional services, your policy must include `service:write` permissions for the additional services to be included in the policy rules.
+
+The policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace.
+
+<CodeTabs>
+
+```hcl
+partition "ptn1" {
+  namespace "ns1" {
+    service "terminating-gateway" {
+       policy = "write"
+    }
+    node_prefix "" {
+      policy = "read"
+    }
+    service "external-service-2" {
+      policy = "write"
+    }
+  }
+  namespace "default" {
+    service "external-service-1" {
+      policy = "write"
+    }
+    node_prefix "" {
+      policy = "read"
+    }
+    agent_prefix "" {
+      policy = "read"
+    }
+  }
+}
+```
+
+```json
+{
+  "partition": {
+    "ptn1": [{
+      "namespace": {
+        "default": [{
+          "agent_prefix": {
+            "": [{
+              "policy": "read"
+            }]
+          },
+          "node_prefix": {
+            "": [{
+              "policy": "read"
+            }]
+          },
+          "service": {
+            "external-service-1": [{
+              "policy": "write"
+            }]
+          }
+        }],
+        "ns1": [{
+          "node_prefix": {
+            "": [{
+              "policy": "read"
+            }]
+          },
+          "service": {
+            "external-service-2": [{
+              "policy": "write"
+            }],
+            "terminating-gateway": [{
+              "policy": "write"
+            }]
+          }
+        }]
+      }
+    }]
+  }
+}
+```
+
+</CodeTabs>
+
+### Register the policy with Consul
+
+After defining the policy, you can register the policy with Consul using the command line or API endpoint.
+
+You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. You must create the policy in the same partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the policy must be created in the `default` namespace. The following example creates the policy in the partition `ptn1` and `default` namespace because the example policy contains permissions for multiple namespaces.
+
+<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 policy defined in `tgw-register.hcl`:
+
+```shell-session
+$ consul acl policy create -partition "ptn1" -namespace "default" \
+    -name "tgw-register" -rules @tgw-register.hcl \
+    -description "Terminating 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 policy defined in `tgw-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": "tgw-register",
+  "Description": "Terminating gateway policy",
+  "Partition": "ptn1",
+  "Namespace": "default",
+  "Rules": "partition \"ptn1\" {\n  namespace \"ns1\" {\n    service \"terminating-gateway\" {\n       policy = \"write\"\n    }\n    node_prefix \"\" {\n      policy = \"read\"\n    }\n    service \"external-service-2\" {\n      policy = \"write\"\n    }\n  }\n  namespace \"default\" {\n    service \"external-service-1\" {\n      policy = \"write\"\n    }\n    node_prefix \"\" {\n      policy = \"read\"\n    }\n    agent_prefix \"\" {\n      policy = \"read\"\n    }\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](/consul/docs/security/acl/auth-methods).
+
+You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the token must be created in the `default` namespace. The following example creates the token in the `default` namespace in the `ptn1` partition because the example policy contains permissions for multiple namespaces.
+
+<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.
+
+```shell-session
+$ consul acl token create -partition "ptn1" -namespace "default" \
+    -description "Terminating gateway token" \
+    -policy-name "tgw-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": "tgw-register"
+    }
+  ],
+  "Partition": "ptn1",
+  "Namespace": "default"
+}'
+```
+
+</Tab>
+
+</Tabs>