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

$ export CONSUL_HTTP_TOKEN=...
$ consul-acl-sync -config config.yaml

secret_id is a credential, so keep the file under sops. Decrypt it to a temporary file for the run with sops exec-file, which leaves no plaintext on disk:

$ sops exec-file --no-fifo config.yaml 'consul-acl-sync -config {}'

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.

Environment variables

• CONSUL_HTTP_TOKEN: Consul ACL management token (required)

License

This project is licensed under the MIT License.