Create a Consul ESM token
This topic describes how to create a token for the Consul external service monitor.
Introduction
Consul external service monitor (ESM) can monitor third-party or external services in contexts where you are unable to run a Consul agent. To learn more about Consul ESM, refer to the Register External Services with Consul Service Discovery tutorial.
Requirements
Core ACL functionality is available in all versions of Consul.
Consul ESM must present a token linked to policies that grant the following permissions:
agent:read
: Enables checking version compatibility and calculating network coordinateskey:write
: Enables storing state in the Consul KV storenode:read
: Enables discovering Consul nodes to monitornode:write
: Enables updating status for the nodes that Consul ESM monitorsservice:write
: Enables Consul ESM to register as a service in the catalogsession:write
: Enables Consul ESM is registered to acquire a leader lockacl:read
: (Enterprise-only) Enables Consul ESM to scan namespaces for nodes and health checks to monitor
Consul ESM only supports default
admin partitions.
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 ESM token in Consul CE
To create a token for Consul ESM, 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 Consul ESM running on an agent with the node name agent1
to monitor two nodes named node1
and node2
. It allows Consul ESM to register into the catalog as the consul-esm
service and write keys with the prefix consul-esm/
in the Consul KV store.
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. Refer to Consul ACL Policy Create for details about the consul acl policy create
command.
The following example registers a policy defined in esm-policy.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 example creates an ACL token linked to the policy esm-policy
.
Consul ESM token in Consul Enterprise
To create a token for Consul ESM, 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 Consul ESM running on an agent named agent1
to monitor two nodes named node1
and node2
. It allows Consul ESM to register into the catalog as the consul-esm
service, to write keys with the prefix consul-esm/
in the Consul KV store, and to scan the default
and ns1
namespaces for nodes and health checks to monitor.
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 scopes. The example policy contains permissions for multiple namespaces in multiple partitions. You must create ACL policies that grant permissions for multiple namespaces in multiple partitions in the default
namespace and 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 command registers a policy defined in esm-policy.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.
You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token must be created in the partition and namespace where the policy was created. The following example creates an ACL token 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 esm-policy
.