consul snapshot save: Back Up Consul State in CI
consul snapshot save writes an atomic point-in-time backup of the Consul servers KV, catalog, ACLs, and sessions to a file.
A scheduled CI job that runs consul snapshot save is the standard way to back up Consul. The snapshot restores with consul snapshot restore.
What it does
consul snapshot save captures the entire server state managed by Raft (KV store, service catalog, ACLs, sessions, prepared queries) into a single file. The save is atomic and consistent; by default it reads from the leader for the freshest data.
Common usage
consul snapshot save backup.snap
# verify a snapshot file
consul snapshot inspect backup.snap
# restore (overwrites cluster state)
consul snapshot restore backup.snapOptions
| Flag | What it does |
|---|---|
| <file> | Path to write the snapshot to (required) |
| -stale | Allow any server to serve the snapshot (not just leader) |
| -token <token> | ACL token (needs management privileges) |
| -datacenter <dc> | Snapshot a specific datacenter |
In CI
Run it on a schedule and ship the file off-runner (object storage), then optionally consul snapshot inspect to confirm it is valid. -stale trades a tiny staleness for not depending on leader availability, useful when the leader is briefly unreachable.
Common errors in CI
"Error saving snapshot: Unexpected response code: 500 (No cluster leader)" means there is no Raft leader right now; wait for an election or pass -stale. "Unexpected response code: 403 (Permission denied)" means the token lacks management rights. "permission denied" writing the file means the output directory is not writable; target /tmp.