Skip to main content
In this guide, you’ll learn how to automate backups of your Consul data using the Consul Snapshot Agent—an enterprise-only feature that takes and stores snapshots on a schedule.

​
Overview

Consul’s open source edition requires manual snapshots. With a valid enterprise license, you can deploy the Snapshot Agent to automatically capture and store snapshots at defined intervals, either locally or in AWS S3.

​
Prerequisites

  • Enterprise license installed on every Consul server
  • Consul binary present on all nodes
  • A running cluster with two servers and two clients
  • AWS credentials configured for S3 storage (if using S3)
Make sure your Enterprise license is active and that your IAM user has write permissions for the S3 bucket.

​
Verify Cluster Membership

Run this command on any server to confirm all nodes are online: 
consul members
Expected output: 
server-1  10.0.0.1:8301  alive
server-2  10.0.0.2:8301  alive
client-1  10.0.1.1:8301  alive
client-2  10.0.1.2:8301  alive

​
Create a Systemd Unit for the Snapshot Agent

The Snapshot Agent runs as a separate Consul process in agent mode. Place this file at /etc/systemd/system/consul-snapshot.service: 
[Unit]
Description="HashiCorp Consul Snapshot Agent"
Documentation=https://www.consul.io/docs
Requires=network-online.target
After=consul.service
ConditionFileNotEmpty=/etc/consul-snapshot.d/consul-snapshot.json

[Service]
User=consul
Group=consul
ExecStart=/usr/local/bin/consul snapshot agent -config-file=/etc/consul-snapshot.d/consul-snapshot.json
KillMode=process
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

​
Configure the Snapshot Agent

Create /etc/consul-snapshot.d/consul-snapshot.json with your settings: 
{
  "snapshot_agent": {
    "http_addr": "127.0.0.1:8500",
    "datacenter": "",
    "snapshot": {
      "interval": "30m",
      "retain": 336,
      "deregister_after": "8h",
      "service": "consul-snapshot"
    },
    "aws_storage": {
      "s3_region": "us-east-1",
      "s3_bucket": "us-east-1-krausen-consul-snapshots"
    }
  }
}
ParameterDescriptionExample
http_addrAddress of the local Consul HTTP API127.0.0.1:8500
intervalHow often to take a snapshot30m
retainNumber of snapshots to keep336 (≈2 weeks at 30 m intervals)
deregister_afterTime to remove agent if it fails to renew leadership8h
serviceService name under which the agent registers in Consulconsul-snapshot
s3_regionAWS region for S3 storageus-east-1
s3_bucketS3 bucket to store snapshotsus-east-1-krausen-consul-snapshots
Adjust values to match your environment and naming conventions.

​
Start and Enable the Service

sudo systemctl enable consul-snapshot.service
sudo systemctl start consul-snapshot.service

​
Verify Service Status and Logs

sudo systemctl status -l consul-snapshot.service
Sample log output: 
● consul-snapshot.service - "HashiCorp Consul Snapshot Agent"
   Loaded: loaded (/etc/systemd/system/consul-snapshot.service; enabled)
   Active: active (running) since Thu 2021-02-11 21:36:36 UTC
 Main PID: 6351 (consul)
    Tasks: 5
   Memory: 2.4M
      CPU: 69ms
   CGroup: /system.slice/consul-snapshot.service
           └─6351 /usr/local/bin/consul snapshot agent -config-file=/etc/consul-snapshot.d/consul-snapshot.json

Feb 11 21:36:36 server-1 consul[6351]: [INFO]  license: Automated Backups feature is now licensed
Feb 11 21:36:36 server-1 consul[6351]: [INFO]  snapshot: Waiting to obtain leadership...
Feb 11 21:36:36 server-1 consul[6351]: [INFO]  snapshot: Obtained leadership
Feb 11 21:36:36 server-1 consul[6351]: [INFO]  snapshot: Saved snapshot: id=1613079399661741730

​
Confirm Snapshots in S3

  1. Open the AWS S3 Console.
  2. Navigate to your bucket (us-east-1-krausen-consul-snapshots).
  3. Verify that snapshot files appear under the configured prefix at the expected interval.

​
High Availability & Leadership Failover

Deploy a second agent on another server: 
sudo systemctl start consul-snapshot.service
sudo systemctl status -l consul-snapshot.service
It will log: 
[INFO]  snapshot: Waiting to obtain leadership...
To test failover, stop the first agent: 
sudo systemctl stop consul-snapshot.service   # on server-1
Then restart on server-2: 
sudo systemctl restart consul-snapshot.service  # on server-2
sudo systemctl status -l consul-snapshot.service
You should see: 
[INFO]  snapshot: Obtained leadership
[INFO]  snapshot: Saved snapshot: id=1613079648559762150
Confirm new snapshots in the S3 bucket.

​
Cleanup

When you’re done: 
sudo systemctl stop consul-snapshot.service
sudo systemctl disable consul-snapshot.service

​
References

Watch Video

Practice Lab