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"
    }
  }
}

Parameter	Description	Example
`http_addr`	Address of the local Consul HTTP API	`127.0.0.1:8500`
`interval`	How often to take a snapshot	`30m`
`retain`	Number of snapshots to keep	`336` (≈2 weeks at 30 m intervals)
`deregister_after`	Time to remove agent if it fails to renew leadership	`8h`
`service`	Service name under which the agent registers in Consul	`consul-snapshot`
`s3_region`	AWS region for S3 storage	`us-east-1`
`s3_bucket`	S3 bucket to store snapshots	`us-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

Open the AWS S3 Console.
Navigate to your bucket (us-east-1-krausen-consul-snapshots).
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