Skip to main content

Snapshots

Snapshots capture the entire state of your Consul cluster: KV data, ACL tokens, sessions, prepared queries, and the service catalog. Unlike the KV-to-Git sync (which only tracks KV), snapshots give you a full point-in-time backup.

What's included​

A Consul snapshot contains:

  • All KV data (every key and value)
  • ACL tokens and policies
  • Sessions
  • Prepared queries
  • Service catalog registrations
  • Raft metadata

This is the same format produced by consul snapshot save -- you can restore it with consul snapshot restore.

Taking a snapshot​

CLI​

consul-guardian snapshot save \
  --consul-addr http://localhost:8500 \
  --storage-type local \
  --storage-path ./snapshots

Output:

Snapshot saved: dc1/consul-dc1-20260404-143000.snap
  Size:     2048576 bytes
  SHA-256:  a1b2c3d4e5f6...
  Duration: 320ms
  Retention: kept 10, deleted 2

Dashboard​

Navigate to the Snapshots page and click "Take Snapshot". The snapshot is saved to the configured storage backend and appears in the list.

With S3 storage​

consul-guardian snapshot save \
  --storage-type s3 \
  --bucket consul-backups \
  --s3-prefix "production/" \
  --s3-region us-east-1

S3 credentials are read from the standard AWS credential chain (environment variables, ~/.aws/credentials, IAM role, etc.).

Storage backends​

Local filesystem​

consul-guardian snapshot save \
  --storage-type local \
  --storage-path /data/consul-snapshots

Snapshots are stored as files:

/data/consul-snapshots/
  dc1/consul-dc1-20260404-143000.snap
  dc1/consul-dc1-20260403-143000.snap
  dc1/consul-dc1-20260402-143000.snap

Amazon S3​

consul-guardian snapshot save \
  --storage-type s3 \
  --bucket my-consul-backups \
  --s3-prefix "snapshots/" \
  --s3-region eu-west-1

Required IAM permissions:

{
  "Effect": "Allow",
  "Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket", "s3:DeleteObject"],
  "Resource": [
    "arn:aws:s3:::my-consul-backups",
    "arn:aws:s3:::my-consul-backups/*"
  ]
}

Retention policies​

Retention is enforced automatically after each snapshot. Configure via CLI flags or the config file.

Count-based​

Keep the last N snapshots:

consul-guardian snapshot save --retention-count 30

Older snapshots are deleted. Guardian never deletes the last remaining snapshot, even if the count is set to 0.

Age-based (config file)​

snapshot:
  retention:
    count: 30
    max_age: "720h"  # 30 days

Both policies can be combined. A snapshot is deleted if it exceeds the count limit or the age limit.

Stale reads​

By default, snapshots use stale reads (--stale=true). This reduces load on the Consul leader by allowing the snapshot to be served by any server. The trade-off is that the snapshot may be slightly behind (typically a few hundred milliseconds).

For a strictly consistent snapshot:

consul-guardian snapshot save --stale=false

Restoring from a snapshot​

Consul Guardian takes the snapshots, but restoring is done with the standard consul CLI:

consul snapshot restore /data/consul-snapshots/dc1/consul-dc1-20260404-143000.snap

This replaces the entire cluster state. It's a destructive operation -- use it only for disaster recovery.

Real-world example​

A team runs daily snapshots to S3 with 30-day retention:

snapshot:
  storage:
    type: s3
    bucket: acme-consul-backups
    prefix: "production/"
    region: us-east-1
  retention:
    count: 30

One month later, a Consul cluster upgrade goes wrong and corrupts the Raft log. The team recovers by:

  1. Standing up a new Consul cluster.
  2. Downloading yesterday's snapshot from S3.
  3. Running consul snapshot restore.
  4. Using Guardian's KV restore to apply any changes made since the last snapshot.

Full recovery in under 15 minutes, zero data loss.