Create a snapshot agent token
This topic describes how to create a token for the Consul snapshot agent.
This feature requires Consul Enterprise(opens in new tab).
Introduction
The consul snapshot agent
command starts a process that takes snapshots of the state of the Consul
servers and either saves them locally or pushes them to a remote storage service. Refer to Consul Snapshot Agent for additional information.
Requirements
Core ACL functionality is available in all versions of Consul.
Requirements for the agent
command
The agent
subcommand requires Consul Enterprise. All other snapshot
subcommands are available in Consul Community Edition.
Snapshot agent ACL requirements
The Consul snapshot agent must present a token linked to policies that grant the following set of permissions.
acl:write
: Enables the agent read and snapshot ACL datakey:write
: Enables the agent to create a key in the Consul KV store that serves as a leader election lock when multiple snapshot agents are running in an environmentsession:write
: Enables the agent to create sessions for the specified Consul node where it is runningservice:write
: Enables the agent to register into 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:
Create a token
To create a token for the snapshot agent, 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 for a snapshot agent running on a node named server-1234
to register into the catalog as the consul-snapshot
service. It uses the key consul-snapshot/lock
for a leader election lock.
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. Policies are only valid in the specified scopes. You must create the policy for the snapshot agent in the default
namespace in the default
partition.
Run the consul acl policy create
command and specify the policy rules to create a policy. Refer to Consul ACL Policy Create for details about the consul acl policy create
command.
The following example registers a policy defined in snapshot-agent.hcl
:
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.
You can specify an admin partition and namespace when creating tokens in Consul Enterprise. Tokens are only valid in the specified scopes. The snapshot agent token must be created in the default
namespace in the default
partition.
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 snapshot-agent
.