Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท ACLs and Security

Writing Consul ACL Rules and Policies

Write Consul ACL rules for services, nodes, key-value paths, sessions and the agent: exact versus prefix matching, access levels, and creating policies with the CLI.

A policy is a list of rules. Each rule names a resource type, a segment (an exact name or a prefix) and an access level. Writing good rules is the core skill of Consul security: grant exactly what a token needs, nothing more. This lesson covers the syntax, the matching order and a policy for a typical web service.

The product cannot run on this site. The rules and commands are read-only; the runnable examples are stand-in evaluators for the matching logic.

Anatomy of a rule

HCL
service "web" {
  policy = "write"
}

key_prefix "config/web/" {
  policy = "read"
}
  • Resource type (service, key_prefix...): what kind of thing is being protected.
  • Segment ("web"): the specific name or, for _prefix types, a prefix.
  • policy: the access level: read, write or deny. Some resources accept list for key-value listings.

Resource types

Type Protects Notes
service / service_prefix Catalog service registration and reads write registers; read discovers
node / node_prefix Node registration and reads Needed by agents and for DNS node lookups
key / key_prefix Key-value entries read, write, list, deny
session / session_prefix Sessions for locks and leader election
agent / agent_prefix Agent endpoints such as members, metrics and reload Control by node name
event / event_prefix User events
query / query_prefix Prepared queries
operator Operator endpoints (Raft, autopilot, keyring) Single-valued: operator = "read"
keyring Gossip keyring keyring = "write"
mesh Mesh-wide settings, proxy defaults mesh = "write"
acl Managing ACLs acl = "write" is nearly administrator

Single-valued resources are written as operator = "read" rather than a block.

Exact versus prefix, and longest match

Rules without _prefix match one name exactly; _prefix rules match any name that begins with the text. If several rules match, Consul picks the most specific: an exact rule beats a prefix rule, and among prefixes the longest wins. An empty prefix "" matches everything and is the least specific.

HCL
key_prefix ""          { policy = "deny"  }   # default for all keys
key_prefix "config/"   { policy = "read"  }
key_prefix "config/web/" { policy = "write" }
key "config/web/secret"  { policy = "deny" }
  • config/other/x โ†’ read (prefix config/)
  • config/web/port โ†’ write (longer prefix)
  • config/web/secret โ†’ deny (exact beats prefix)
  • data/x โ†’ deny (empty prefix)
Python Stand-in: longest-prefix rule matching

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Access levels

  • read: view the resource. For services this includes discovery; for keys, reading values.
  • write: change it. Implies read.
  • deny: refuse access, even to things the token would otherwise reach through another policy.
  • list (key prefixes only): list key names under a prefix. Check your version's reference for how read and list interact before relying on either for enumeration.

A deny is the one rule that can override other policies on a token, so use it sparingly to carve exceptions.

A policy for a service and its sidecar

A token for web and its sidecar proxy needs to register the service, read other services and nodes, and read its own configuration:

HCL
service "web" {
  policy = "write"
}

service "web-sidecar-proxy" {
  policy = "write"
}

service_prefix "" {
  policy = "read"
}

node_prefix "" {
  policy = "read"
}

key_prefix "config/web/" {
  policy = "read"
}

Reading all services and nodes (service_prefix "", node_prefix "") is what lets the sidecar find its upstreams. Without node read, DNS and health lookups fail with permission errors. Consul can generate exactly this shape for you with a service identity (next lessons), which is less error-prone than handwriting.

Creating and testing policies

Terminal
consul acl policy create -name web-service -rules @web-policy.hcl
consul acl policy list
consul acl policy read -name web-service
consul acl policy update -name web-service -rules @web-policy.hcl
consul acl token create -description "web" -policy-name web-service

Passing -rules @file.hcl reads the rules from a file. Keep policy files in Git and apply them through automation (Terraform's Consul provider, a script, or your pipeline) so changes get reviewed.

Creating a policy with invalid HCL fails with a parse error, so mistakes surface at write time. For the runtime question "may this token do X?", log in with the token and try, or use consul acl token read -self to see which policies it received. When a rule seems to not work, check it propagated (ACL changes are cached for acl.token_ttl, 30 seconds by default).

Datacenter scoping

A policy can be limited to datacenters when you create it:

Terminal
consul acl policy create -name web-dc1 -datacenter dc1 -rules @web.hcl

Without -datacenter the policy is valid everywhere ACLs replicate from the primary datacenter.

Python Stand-in: lint a policy for risky rules

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Using service_prefix "" { policy = "write" } for convenience. It lets the token register any service name, including impersonating another team's.
  • Forgetting node_prefix read. DNS lookups and health queries break.
  • Putting secrets in a key readable by a broad prefix. Carve out exceptions with a longer deny rule or keep secrets in Vault.
  • Expecting changes to be instant. Cached tokens use old rules until the cache expires.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which rule wins when key_prefix "config/" is read and key "config/secret" is deny?

    Exact matches take precedence over prefix matches, so config/secret is denied.
  2. 2. Among several matching prefix rules, which applies?

    The most specific, meaning longest, prefix is chosen.
  3. 3. Which permission lets a sidecar discover upstream services?

    Discovery needs read on services and nodes in the catalog.
  4. 4. How do you write the operator permission?

    Single-valued resources such as operator, keyring and mesh use a simple assignment.
  5. 5. Why might a policy change not take effect immediately?

    Agents cache token and policy resolution for acl.token_ttl (30 seconds by default).

Summary

  • A rule is resource type + segment + read, write or deny; _prefix types match by prefix.
  • The most specific match wins: exact beats prefix, longer prefix beats shorter.
  • Create policies with consul acl policy create -rules @file.hcl and keep them in version control.
  • Avoid empty-prefix write rules and administrator permissions for ordinary services.

Next: Tokens, Roles and Identities