HashiCorp Certified: Consul Associate Certification

Back up and Restore

Demo Using the Consul Snapshot Agent Enterprise

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)

Warning

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

Watch video content

Practice Lab

Practice lab

Previous
Consul Snapshot Agent Enterprise