This topic describes how to set up Consul's access control list (ACL) system in cluster deployments that span multiple data centers. This documentation is applicable to new clusters rather than existing clusters.

Requirements

Consul versions 1.4.0 and later

Configure ACLs in the Primary Datacenter

In a federated Consul deployment, one of the datacenters is marked as the primary datacenter. The acl configuration block should be added to the primary datacenter server's configuration file as shown in the following example.

See the ACL Config Stanza for more detailed descriptions of each option.

bootstrap_expect =  3
primary_datacenter =  "PRIMARY_DATACENTER_VALUE"
acl = {
 enabled =  true
 default_policy = "deny"
 down_policy = "deny"
 enable_token_persistence = true
 enable_token_replication = true
 tokens = {
   initial_management =  "ACL_MANAGEMENT_TOKEN"
   agent = "YOUR_ACL_AGENT_TOKEN"
  }
}

{
  "bootstrap_expect": 3,
  "primary_datacenter": "PRIMARY_DATACENTER_VALUE",
  "acl": {
    "enabled": true,
    "default_policy": "deny",
    "down_policy": "deny",
    "enable_token_persistence": true,
    "enable_token_replication": true,
    "tokens": {
      "initial_management": "ACL_MANAGEMENT_TOKEN",
      "agent": "ACL_AGENT_TOKEN"
    }
  }
}

The ACL agent token can also be set using the consul acl set-agent-token CLI as shown below.

$ consul acl set-agent-token agent "<agent token here>"

Configure Servers in Secondary Datacenters

Servers in secondary data centers must be configured to point to the primary data center as shown in the following example. Secondary data centers also need the ACL replication token provided to them.

Create the replication token for ACL Management

Replication tokens are needed for ACL token replication and to create both configuration entries and auth methods in connected secondary datacenters.

Replication tokens require the following permissions:

• acl = "write": The permission allows you to replicate tokens.
• operator = "write": This permission enables the proxy-default configuration entries to be replicated and enables CA certificate signing in the secondary datacenter.
• policy = "read" and intentions = "read" in the service_prefix field: These permissions enable service-default configuration entries, CA, and intention data to be replicated for all services.

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

Create a replication policy with the following command:

$ consul acl policy create -name replication -rules @replication-policy.hcl

Use your newly created policy to create the replication token.

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

Configure the replication token in Secondary Datacenters

Add the replication token generated above, to the ACL stanza in secondary datacenters.

primary_datacenter = "PRIMARY_DATACENTER_NAME"
acl = {
   enabled = true
   default_policy =  "deny"
   down_policy =  "deny"
   tokens = {
      agent =  "ACL_AGENT_TOKEN"
      replication = "ACL_REPLICATION_TOKEN"
   }
}

{
  "primary_datacenter": "PRIMARY_DATACENTER_VALUE",
  "acl": {
    "enabled": true,
    "default_policy": "deny",
    "down_policy": "deny",
    "tokens": {
      "agent": "ACL_AGENT_TOKEN",
      "replication": "ACL_REPLICATION_TOKEN"
    }
  }
}

WAN Join Servers

This step is needed for new federated cluster deployments in order for servers in each federated datacenter to discover each other.

Run the following command from one of the server nodes.

$ consul join -token="ACL_MANAGEMENT_TOKEN" -wan [server 1, server 2, ...]

Configure Clients in Secondary Datacenters

When ACLs are enabled, client agents need a special token known as the agent token to perform internal operations. Agent tokens need to have the right policies for node related actions, including registering itself in the catalog, updating node level health checks, and performing anti-entropy syncing.

Generate Agent ACL Token

ACL Node Identities were introduced in Consul 1.8.1 and enable easily creating agent tokens with appropriately scoped policies.

To generate the ACL token using node identity, run the following command:

$ consul acl token create -node-identity=<NODE_NAME>:<DATACENTER>

Configure clients to use the ACL agent token

Update the client agents to include the token value from the previous step. Replace the ACL_AGENT_TOKEN value below with the secret ID value from the command output.

primary_datacenter = "PRIMARY_DATACENTER_NAME"
acl = {
   enabled = true
   default_policy =  "deny"
   down_policy =  "deny"
   tokens = {
      agent =  "ACL_AGENT_TOKEN"
   }
}

{
  "primary_datacenter": "PRIMARY_DATACENTER_VALUE",
  "acl": {
    "enabled": true,
    "default_policy": "deny",
    "down_policy": "deny",
    "tokens": {
      "agent": "ACL_AGENT_TOKEN"
    }
  }
}

Note that client agents have to be restarted for ACL related configuration changes to take effect.

Summary

After completing the above steps, a federated Consul cluster can be used with ACLs. Refer to ACL Replication Guide for more on this topic.