Vault - snapshot.json (Raft snapshot agent)

category: solutionz · date: 2024-12-31 · updated: 2026-10-02 · author: LALA

Vault Solution · Config document · referenced from Raft snapshots, backup and restore

noteThis file holds an AppRole SecretID and S3 keys in clear text. On the hosts it was readable by the vault user only; here every secret is a placeholder.

Configuration of the third-party Raft snapshot agent that ran beside every Vault node. The agent asks the local node whether it is the leader, and only the leader takes a snapshot and uploads it. This is the final form, writing straight to S3-compatible object storage.

Item	Value
Path on the host	`/etc/vault.d/snapshot.json`
Owner	`vault:vault`
Deployed on	all Vault nodes
Read by	`vault_raft_snapshot_agent` 0.3.1

The file

json

{
   "addr":"http://127.0.0.1:8200",
   "retain":9223372036854775807,
   "frequency":"7200s",
   "role_id":"<APPROLE_SNAPSHOTS_ROLE_ID>",
   "secret_id":"<APPROLE_SNAPSHOTS_SECRET_ID>",
   "aws_storage":{
      "access_key_id":"<S3_ACCESS_KEY_ID>",
      "secret_access_key":"<S3_SECRET_ACCESS_KEY>",
      "s3_region":"dc1",
      "s3_bucket":"prod-vault",
      "s3_key_prefix":"snapshots",
      "s3_endpoint":"https://s3-a.example.net",
      "s3_force_path_style":true
   }
}

Settings

Key	Value as built	Meaning
`addr`	`http://127.0.0.1:8200`	The loopback listener of the local node, no TLS
`retain`	`9223372036854775807`	Number of snapshots to keep; the largest 64-bit integer, so the agent never deleted anything and retention was left to the storage
`frequency`	`7200s`	A snapshot every two hours
`role_id`, `secret_id`	placeholders	AppRole `snapshots`, bound to `snapshots-policy`
`s3_key_prefix`	`snapshots`	Directory inside the bucket
`s3_force_path_style`	`true`	Needed by most S3-compatible stores

Earlier forms

Period	Storage block	`retain`	`frequency`
First deployment, PROD and NONPROD	`"local_storage": {"path": "/data/raft/snapshots"}`	`168`	`7200s`
First deployment, COMMON	`"local_storage": {"path": "/data/raft/snapshots"}`	`14`	`1d`
Final	`aws_storage` as shown	unlimited	`7200s`

Checked against Vault 2.1

The agent is abandoned. Lucretius/vault_raft_snapshot_agent is marked deprecated by its author; the last release, 0.3.1, is from 2021. The design document already noted this in 2024.
Vault itself still has no free replacement. Automated snapshots (sys/storage/raft/snapshot-auto) remain an Enterprise feature in 2.1.
What to use instead. Either the maintained fork Argelbargel/vault-raft-snapshot-agent, whose compatibility with Vault 2.x I have not verified, or a systemd timer that runs vault operator raft snapshot save on the leader and uploads the file. The command and the policy path are unchanged.
addr over plain HTTP works only because of the loopback listener without TLS. If that listener goes, the agent needs the TLS address and the CA.

See the raft operator commands.