Create a mesh gateway token
This topic describes how to create a token for a mesh gateway.
Introduction
Mesh gateways enable service-to-service traffic between Consul datacenters or between Consul admin partitions. They also enable datacenters to be federated across wide area networks. Refer to Mesh Gateways for additional information.
Gateways must present a token linked to policies that grant the appropriate set of permissions in order to be discoverable and to route to other services in a mesh.
Requirements
Core ACL functionality is available in all versions of Consul.
The mesh gateway must present a token linked to a policy that grants the following permissions:
mesh:write
to obtain leaf certificates for terminating TLS connectionspeering:read
for Consul cluster peering through mesh gateways. If you are not using cluster peering or if the mesh gateway is not in thedefault
partition, then you can omit thepeering:read
permission.service:write
to allow the mesh gateway to register into the catalogservice:read
for all services andnode:read
for all nodes in order to discover and route to servicesagent:read
to enable theconsul 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 theagent:read
permission.
Authentication
You must provide an ACL token linked to a policy with acl:write
permissions to create and modify ACL tokens and policies using the CLI or API.
You can provide the token manually using the -token
option on the command line, but we recommend setting the CONSUL_HTTP_TOKEN
environment variable to simplify your workflow:
The Consul CLI automatically reads the CONSUL_HTTP_TOKEN
environment variable so that you do not have to pass the token to every Consul CLI command.
To authenticate calls to the Consul HTTP API, you must provide the token in the X-Consul-Token
header for each call:
To learn about alternative ways to authenticate, refer to the following documentation:
Consul CE
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 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 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 mesh-gateway
and to operate as a mesh gateway.
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.
Run the consul acl policy create
command and specify the policy rules to create a policy. The following example registers a policy defined in mgw-register.hcl
:
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.
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 for details about the consul acl token create
command.
The following command creates the ACL token linked to the policy mgw-register
.
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 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 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 example policy is defined in a file. The policy grants the appropriate permissions to register as a service named mesh-gateway
and to operate as a mesh gateway in the 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.
Run the consul acl policy create
command and specify the policy rules to create a policy. The following example registers a 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.
Refer to Consul ACL Policy Create for details about the consul acl policy create
command.
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.
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 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
.
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 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 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 example policy is defined in a file. The policy grants the appropriate permissions to register as a service named mesh-gateway
and to operate as a mesh gateway in a 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.
Run the consul acl policy create
command and specify the policy rules to create a policy. The following example registers a 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
.
Refer to Consul ACL Policy Create for details about the consul acl policy create
command.
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.
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 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
.