Create an agent token
This topic describes how to create a token that you can use to register an agent into the catalog.
Introduction
Consul agents must present a token linked to policies that grant the appropriate set of permissions in order to register into the catalog and to discover services and nodes in the catalog.
Specify the agent
token to the Consul agent so that it can present the token when it registers into the catalog.
Node identities versus custom policies
You can create tokens linked to custom policies or to node identities. Node identities are constructs in Consul that enable you to quickly grant permissions for a group of agents, rather than create similar policies for each agent.
We recommend using a node identity to grant permissions to the agent rather than creating a custom policy. This is because node identities automatically grant the node node:write
and service:read
permission.
Your organization may have requirements or processes for deploying services in a way that is inconsistent with service and node identities. In these cases, you can create custom policies and link them to tokens.
Requirements
Core ACL functionality is available in all versions of Consul.
The agent token must be linked to policies that grant the following permissions:
node:write
: Enables the agent to update the catalog.service:read
: Enables the agent to discover other services in the catalog
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:
Node identity in Consul CE
Refer to Node identities for information about node identities that you can link to tokens.
You can manually create 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 or node identity to link to create a token. Refer to Consul ACL Token Create for details about the consul acl token create
command.
The following command creates an ACL token linked to a node identity for a node named node1
in the datacenter dc1
.
Node identity in Consul Enterprise
Refer to Node identities for information about node identities that you can link to tokens.
You can manually create 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 or node identity to link to create a token. 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 following example creates an ACL token that the agent can use to register in partition ptn1
in datacenter dc1
:
Custom policy in Consul CE
When you are unable to link tokens to a node identity, you can define policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog.
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 write
permission for node node1
so that the Consul agent can register into the catalog. It grants read
permissions to discover services in the catalog.
Register the policy with Consul
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
Run the consul acl policy create
command and specify the policy rules to create a policy. The following example registers a policy defined in node1-register.hcl
:
Refer to Consul ACL Policy Create for details about the consul acl policy create
command.
Link the policy to a token
After registering the policies 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 node1-register
.
Custom policy in Consul Enterprise
When you are unable to link tokens to a node identity, you can define policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog.
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 write
permission for node node1
in partition ptn1
so that the Consul agent can register into the catalog. It grants read
permissions to discover services in any namespace in the ptn1
partition.
Register the policy with Consul
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
Run the consul acl policy create
command and specify the policy rules to create a policy. The following example registers a policy defined in node1-register.hcl
:
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.
Apply the token
Configure the Consul agent to present the token by either specifying the token in the agent configuration file or by using the consul set-agent-token
command.
Apply the token in a file
Specify the token in the acl.token.agent
field of the agent configuration file so that the agent can present it and register into the catalog on startup.
Apply the token with a command
Set the agent
token using the consul set-agent-token
command. The following command configures a running Consul agent token with the specified token.