Create a DNS token

This topic describes how to create a token that enables the Consul DNS to query services in the network when ACLs are enabled.

Introduction

The Consul binary ships with a DNS server that you can use for service discovery in your network. The agent that fulfills DNS lookups requires appropriate ACL permissions to discover services, nodes, and prepared queries registered in Consul.

A Consul agent must be configured with a token linked to policies that grant the appropriate set of permissions.

Specify the default token to the Consul agent to authorize the agent to respond to DNS queries. Refer to DNS usage overview for details on configuring and using Consul DNS.

Requirements

Core ACL functionality is available in all versions of Consul.

The DNS token must be linked to policies that grant the following permissions:

service:read: Enables the agent to perform service lookups for DNS
node:read: Enables node lookups over DNS
query:read: Enables the agent to perform prepared query lookups for DNS

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:

$ export CONSUL_HTTP_TOKEN=<acl-token-secret-id>

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:

$ curl --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" ...

To learn about alternative ways to authenticate, refer to the following documentation:

Create a DNS token

Run the consul acl token create CLI command and specify the builtin/dns templated policy to create a DNS token.

$ consul acl token create -name "dns-token" -templated-policy "builtin/dns"

Apply the token

Configure the Consul agent with 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 dns field of the agent configuration file so that the agent can present it and register into the catalog on startup.

acl = {
  enabled = true
  tokens = {
    dns = "<token>"
    ...
  }
  ...
}

Apply the token with a command

Set the dns token using the set-agent-token command. The following command configures a running Consul agent token with the specified token.

$ consul set-agent-token dns <acl-token-secret-id>