Create a replication token

This topic describes how to configure an ACL token for ACL replication between WAN-federated datacenters. If your Consul clusters are connected through peer connections, ACL replication is not required. To learn more about cluster peering, refer to the comparison between WAN federation and cluster peering.

Introduction

Consul agents must present a token linked to policies that grant the appropriate set of permissions. Specify the replication token on each server in a non-primary datacenter. For hands-on instructions on how to configure ACL replication across datacenters, refer to the ACL Replication for Multiple Datacenters tutorial.

Requirements

Core ACL functionality is available in all versions of Consul.

For a Consul server agent with ACL replication enabled in a secondary datacenter, the token must be linked to a policy that grants the following permissions:

• acl:write: Enables replication of ACL resources
• operator:write: Enables replication of the proxy-defaults configuration entry and enables CA certification signing in the secondary datacenter
• service:read and intention:read: Enables replication of the service-defaults and intentions configuration entries

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:

• CLI Authentication
• API Authentication

Replication token in Consul CE

To create a token for ACL replication, 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 ACL replication.

acl = "write"
operator = "write"
service_prefix "" {
  policy = "read"
  intentions = "read"
}

{
  "acl": "write",
  "operator": "write",
  "service_prefix": {
    "": [{
      "intentions": "read",
      "policy": "read"
    }]
  }
}

Register the policy with Consul

After defining the policy, you can register the policy with Consul using the command line or API endpoint.

$ consul acl policy create \
    -name "acl-replication" -rules @acl-replication.hcl \
    -description "ACL replication token"

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "acl-replication",
  "Description": "ACL replication",
  "Rules": "acl = \"write\"\noperator = \"write\"\nservice_prefix \"\" {\n  policy = \"read\"\n  intentions = \"read\"\n}\n"
}'

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.

$ consul acl token create \
    -description "ACL replication" \
    -policy-name "acl-replication"

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "acl-replication"
    }
  ]
}'

Replication token in Consul Enterprise

To create a token for ACL replication, 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 following example policy grants the appropriate permissions for ACL replication.

operator = "write"
service_prefix "" {
  policy = "read"
  intentions = "read"
}
namespace_prefix "" {
  acl = "write"
  service_prefix "" {
    policy = "read"
    intentions = "read"
  }
}

{
  "namespace_prefix": {
    "": [{
      "acl": "write",
      "service_prefix": {
        "": [{
          "intentions": "read",
          "policy": "read"
        }]
      }
    }]
  },
  "operator": "write",
  "service_prefix": {
    "": [{
      "intentions": "read",
      "policy": "read"
    }]
  }
}

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, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the specified scopes. The policy for replication must be created in the default namespace and default partition.

$ consul acl policy create -partition "default" -namespace "default" \
    -name "acl-replication" -rules @acl-replication.hcl \
    -description "ACL replication token"

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "acl-replication",
  "Description": "ACL replication",
  "Partition": "default",
  "Namespace": "default",
  "Rules": "operator = \"write\"\nservice_prefix \"\" {\n  policy = \"read\"\n  intentions = \"read\"\n}\nnamespace_prefix \"\" {\n  acl = \"write\"\n  service_prefix \"\" {\n    policy = \"read\"\n    intentions = \"read\"\n  }\n}\n"
}'

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.

$ consul acl token create -partition "default" -namespace "default" \
    -description "ACL replication" \
    -policy-name "acl-replication"

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "acl-replication"
    }
  ],
  "Partition": "default",
  "Namespace": "default"
}'

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

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

Apply the token with a command

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

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