minimal consul acl connect setup

Often I need a simple Consul agent with ACLs and Connect enabled for a simple reproduction or demonstration. Although there is a “dev mode” Consul really does not make things easy for getting setup beyond a trivial, insecure agent.

This post is a step-by-step guide on how I start from nothing and end up with a single-node Consul cluster usable with ACLs and Connect enabled. This guide is not about creating a production - ready Consul cluster, for that take a look at the official Consul ACL Guide.

Initial Consul Agent Config

Create the initial Consul agent configuration file consul.hcl. We can turn ACLs on immediately, but there will be warnings in log output until we bootstrap the ACL system, which will happen next.

Note the grpc port and connect configuration - these are required if using Consul Connect features.

server           = true
data_dir         = "/tmp/consul"
log_level        = "info"
bind_addr        = "127.0.0.1"
bootstrap_expect = 1

ports {
  grpc = 8502
}

connect {
  enabled = true
}

acl = {
  enabled                  = true
  default_policy           = "deny"
  enable_token_persistence = true
  tokens = {
    // agent = ...
  }
}

Start Consul Agent

Now we are ready to start the Consul agent. Use the agent configuration file we created from above.

consul agent -config-file=consul.hcl

Bootstrap ACL System

In another terminal, we can use the Consul CLI to interact with the Consul agent. The first thing we need to do is activate the ACL subsystem.

consul acl bootstrap

This will generate a Bootstrap Token based on the built-in global-management policy. Copy the SecretID and export it in your environment so we can continue using the Consul CLI.

export CONSUL_HTTP_TOKEN=<secret-id>

Create an Agent Token

In the initial Consul agent configuration we commented out the line for agent = ..., because on first startup we do not have a token from Consul to give back to Consul as an agent token. We must create an ACL policy, then derive an ACL token from that policy ourselves, then set that token in the Consul agent configuration.

Create the agent policy file consul-agent-policy.hcl.

node_prefix "" {
  policy = "write"
}

Now create the Consul ACL policy using that policy file.

consul acl policy create -name consul-agent-policy -rules @consul-agent-policy.hcl

Now that the policy is registered we can generate an ACL token from it.

consul acl token create -description "Consul Agent Token" -policy-name consul-agent-policy

Similar to the bootstrap command this will output an ACL token with a SecretID. Copy that SecretID value and paste it into the agent = <secret-id> line in the Consul agent config. The tokens block will end up looking something like,

tokens {
  agent = "77a6a28a-8614-2a27-e287-169c36872ead"
}

Restart Consul Agent

Restart the Consul agent so that it picks up the new agent token. Consul should now be usable, so long as you generate ACL tokens for your services.

gl;hf!