consul-acl-sync

README

consul-acl-sync

Apply Consul ACL policies and tokens from a YAML configuration.

consul-acl-sync reads a desired-state YAML file and creates or updates the policies and tokens it declares. It is the write side of the pair. Preview changes first with consul-acl-diff, then apply them here.

Usage

$ consul-acl-sync -config config.yaml

See example.yaml for the schema.

The Consul address defaults to http://127.0.0.1:8500. Point it elsewhere with -consul-addr:

$ consul-acl-sync -config config.yaml -consul-addr http://consul.example.com:8500

Design

• Additive only: resources are created or updated, never deleted. A resource that exists in Consul but not in the config is left untouched. Detect it with consul-acl-diff and remove it by runbook.
• Explicit identity: policies are keyed by name, tokens by accessor_id. Nothing is inferred from descriptions.
• Pinned tokens: accessor_id and secret_id are set in the config rather than generated by Consul, so create is deterministic and re-runs are idempotent. An out-of-band deletion is restored to the same token instead of a new one.
• Immutable secrets: secret_id is sent only on create. A token secret cannot change after creation, so updates carry policy and description only.
• Idempotent: applying the same config repeatedly converges. Rules are compared after whitespace normalization, so cosmetic edits are not reapplied.
• Built-in resources: the config declares only what it manages, so built-in policies and system tokens are never touched.

ACL token

The token is read from the CONSUL_HTTP_TOKEN environment variable, following the consul CLI convention, rather than a flag so it does not leak into process listings or shell history. It needs acl:write on a cluster that enforces ACLs.

License

This project is licensed under the MIT License.