Configuration

Consul Guardian reads configuration from a YAML file, environment variables, and command-line flags. Values are merged with this precedence (highest wins):

1. Command-line flags
2. Environment variables (CONSUL_GUARDIAN_ prefix)
3. Config file
4. Built-in defaults

Config file locations

Guardian searches for consul-guardian.yaml in these paths (in order):

1. Path specified by --config
2. Current directory (./consul-guardian.yaml)
3. /etc/consul-guardian/consul-guardian.yaml
4. $HOME/.consul-guardian/consul-guardian.yaml

Full reference

# consul-guardian.yaml

consul:
  # Consul HTTP API address.
  address: "http://127.0.0.1:8500"

  # ACL token. Prefer using the CONSUL_GUARDIAN_CONSUL_TOKEN env var
  # instead of putting tokens in config files.
  token: ""

  # Datacenter name. Leave empty for auto-detection.
  datacenter: ""

watch:
  # KV prefixes to watch. Each prefix gets its own blocking query goroutine.
  prefixes:
    - "config/"
    - "env/"
    - "feature-flags/"

  # Blocking query wait time. How long Consul holds the connection before
  # returning with no changes. Valid range: 10s to 10m.
  poll_interval: "5m"

  # KV prefixes to exclude from watching. Matched client-side after the
  # blocking query returns. Useful for high-churn keys.
  exclude_prefixes:
    - "config/temp/"
    - "config/cache/"

git:
  # Path to the local Git repository. Created automatically if it
  # doesn't exist.
  repo_path: "./consul-backup"

  # Push commits to the configured remote after each commit.
  auto_push: false

  # Git commit author name.
  commit_author: "consul-guardian"

  # Git commit author email.
  commit_email: "guardian@consul.local"

snapshot:
  storage:
    # Storage backend type: "local" or "s3".
    type: "local"

    # Local storage: directory path for snapshot files.
    path: "./snapshots"

    # S3 storage: bucket name.
    bucket: ""

    # S3 storage: key prefix within the bucket.
    prefix: ""

    # S3 storage: AWS region.
    region: ""

  retention:
    # Keep the last N snapshots. Set to 0 for unlimited.
    # Guardian never deletes the last remaining snapshot.
    count: 30

    # Delete snapshots older than this duration. Set to "0" for unlimited.
    # Examples: "720h" (30 days), "2160h" (90 days).
    max_age: "0"

dashboard:
  # HTTP listen address for the dashboard server.
  listen: ":9090"

logging:
  # Log level: debug, info, warn, error.
  level: "info"

  # Log format: text (human-readable) or json (structured).
  format: "text"

Environment variable overrides

Every config value can be set via environment variables. Replace dots with underscores and prefix with CONSUL_GUARDIAN_:

Config key	Environment variable
consul.address	CONSUL_GUARDIAN_CONSUL_ADDRESS
consul.token	CONSUL_GUARDIAN_CONSUL_TOKEN
consul.datacenter	CONSUL_GUARDIAN_CONSUL_DATACENTER
watch.prefixes	CONSUL_GUARDIAN_WATCH_PREFIXES
watch.poll_interval	CONSUL_GUARDIAN_WATCH_POLL_INTERVAL
watch.exclude_prefixes	CONSUL_GUARDIAN_WATCH_EXCLUDE_PREFIXES
git.repo_path	CONSUL_GUARDIAN_GIT_REPO_PATH
git.auto_push	CONSUL_GUARDIAN_GIT_AUTO_PUSH
git.commit_author	CONSUL_GUARDIAN_GIT_COMMIT_AUTHOR
git.commit_email	CONSUL_GUARDIAN_GIT_COMMIT_EMAIL
snapshot.storage.type	CONSUL_GUARDIAN_SNAPSHOT_STORAGE_TYPE
snapshot.storage.path	CONSUL_GUARDIAN_SNAPSHOT_STORAGE_PATH
snapshot.storage.bucket	CONSUL_GUARDIAN_SNAPSHOT_STORAGE_BUCKET
snapshot.storage.prefix	CONSUL_GUARDIAN_SNAPSHOT_STORAGE_PREFIX
snapshot.storage.region	CONSUL_GUARDIAN_SNAPSHOT_STORAGE_REGION
snapshot.retention.count	CONSUL_GUARDIAN_SNAPSHOT_RETENTION_COUNT
snapshot.retention.max_age	CONSUL_GUARDIAN_SNAPSHOT_RETENTION_MAX_AGE
dashboard.listen	CONSUL_GUARDIAN_DASHBOARD_LISTEN
logging.level	CONSUL_GUARDIAN_LOGGING_LEVEL
logging.format	CONSUL_GUARDIAN_LOGGING_FORMAT

ACL requirements

Minimum (watch + drift detection)

Read-only access to KV:

key_prefix "" {
  policy = "read"
}

Full (watch + restore + snapshots)

key_prefix "" {
  policy = "write"
}

session_prefix "" {
  policy = "write"
}

acl = "write"

The acl = "write" permission is required for cluster snapshots. If you only need KV watching and restore (no snapshots), you can omit it.

Create the token

consul acl policy create \
  -name "consul-guardian" \
  -rules @guardian-policy.hcl

consul acl token create \
  -description "Consul Guardian" \
  -policy-name "consul-guardian"

Example configurations

Development

consul:
  address: "http://localhost:8500"

watch:
  prefixes: ["config/"]
  poll_interval: "30s"

git:
  repo_path: "./consul-backup"

logging:
  level: "debug"
  format: "text"

Production

consul:
  address: "http://consul-server.consul.svc.cluster.local:8500"
  datacenter: "us-east-1"

watch:
  prefixes:
    - "config/"
    - "env/"
    - "feature-flags/"
  poll_interval: "5m"
  exclude_prefixes:
    - "config/temp/"

git:
  repo_path: "/data/consul-backup"
  auto_push: true
  commit_author: "consul-guardian"
  commit_email: "guardian@example.com"

snapshot:
  storage:
    type: "s3"
    bucket: "consul-backups-prod"
    prefix: "us-east-1/"
    region: "us-east-1"
  retention:
    count: 90
    max_age: "2160h"

dashboard:
  listen: ":9090"

logging:
  level: "info"
  format: "json"