Recover to a replicated cluster

Appropriate Vault Enterprise license required

Recover and restore a discrete secret from an integrated storage snapshot to a replicated cluster.

Cannot recover discrete data from disabled mounts

You cannot read, list, or recover information from a snapshot for disabled mount paths. Even if you reenable the same plugin at the same path, Vault treats it as a new mount with different internal identifiers and cannot associate the reenabled mount with the underlying storage entries within the snapshot.

Before you start

You must have an integrated storage snapshot. You can only restore data from automatically or manually saved snapshots for integrated storage.
You must have a snapshot from the cluster targeted for restoration.
You must have access to the unseal keys, or the people with unseal keys, for the target cluster
The cluster must have mlock disabled.
The cluster cannot have anoter snapshot loaded.

You must have recover permissions for the secret path you want to recover.
You must be restoring from a supported plugin. Not all secret paths support snapshot operations. Refer to the table below for supported plugins and paths.

Plugin	Path	Supported snapshot operations	Vault version
cubbyhole	`/:secret_name`	`recover`, `read`, `list`	1.20.0
kv (v1)	`/:secret_name`	`recover`, `read`, `list`	1.20.0

Step 1: Load a snapshot

Load the snapshot holding the secret you want to recover:

For disaster recovery clusters, you must load snapshots on the primary cluster.
For performance replication clusters, you can load snapshots on any cluster, but secondary clusters can only perform snapshot operations on paths that correspond to local mounts. You must use the primary performance node to peform snapshot operations on shared paths.

Before you can load a manual snapshot, you must transfer the snapshot file from secure storage to a local path Vault can access.

Use vault operator raft snapshot load to load the snapshot data from a local file and assign a snapshot ID:

$ vault operator raft snapshot load <local_file_path>

For example:

$ vault operator raft snapshot load /tmp/snapshots/20250624-1.snap

Key                                   Value
---                                   -----
cluster_id                            990195d2-9f10-4e5c-84c5-543b4c250dc6
expires_at                            2025-06-14T09:00:00.675319+05:00
snapshot_id                           e57cd0cf-c3fa-4e5e-96ea-4a68fa8f3269
status                                loading

When you use Vault Enterprise with automated snapshots, you can load a snapshot from cloud storage directly from the URL.

Use vault operator raft snapshot load with the snapshot configuration name and cloud storage URL to load a snapshot file and assign a snapshot ID:

$ vault operator raft snapshot load              \
    auto_config_name=<auto_snapshot_config_name> \
    url="<url_of_snapshot_file>"

For example:

$ vault operator raft snapshot load \
    auto_config_name=paris-primary  \
    url="https://bucket.example.com/vault-snapshots/primary/paris-backup.snap"

Key                                   Value
---                                   -----
auto_config_name                      paris-primary
cluster_id                            7430fa38-8fb6-4b35-b2a7-27ed4c831a44
expires_at                            2025-07-16T03:24:42.867531+05:00
snapshot_id                           9465df92-8236-4af9-8cc8-b7460d882e41
status                                loading

Once you start a snapshot load, you can check the load status using vault read and the /sys/storage/raft/snapshot-load endpoint:

$ vault read /sys/storage/raft/snapshot-load/<snapshot_id>

For example:

$ vault read \
    /sys/storage/raft/snapshot-load/9465df92-8236-4af9-8cc8-b7460d882e41

Key                                   Value
---                                   -----
auto_config_name                      paris-primary
cluster_id                            7430fa38-8fb6-4b35-b2a7-27ed4c831a44
expires_at                            2025-07-16T03:24:42.867531+05:00
snapshot_id                           9465df92-8236-4af9-8cc8-b7460d882e41
status                                ready

Before you can load a manual snapshot, you must transfer the snapshot file from secure storage to a local path Vault can access.

Use the /sys/storage/raft/snapshot-load/ endpoint to load the snapshot data from a local file and assign a snapshot ID:

$ curl                                       \
   --request POST                            \
   --header "X-Vault-Token: ${VAULT_TOKEN}"  \
    --data-binary @<local_file_path>         \
    ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load

For example:

$ curl                                            \
   --request POST                                 \
   --header "X-Vault-Token: ${VAULT_TOKEN}"       \
    --data-binary @/tmp/snapshots/20250624-1.snap \
    ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load | jq

{
  "data": {
    "cluster_id": "990195d2-9f10-4e5c-84c5-543b4c250dc6",
    "expires_at": "2025-06-14T09:00:00.675319+05:00",
    "snapshot_id": "e57cd0cf-c3fa-4e5e-96ea-4a68fa8f3269",
    "status": "loading"
  }
}

When you use Vault Enterprise with automated snapshots, you can load a snapshot from cloud storage directly from the URL.

Use the /sys/storage/raft/snapshot-load endpoint with the snapshot configuration name and cloud storage URL to load a snapshot file and assign a snapshot ID:

$ curl                                      \
   --request POST                           \
   --header "X-Vault-Token: ${VAULT_TOKEN}" \
   --data '{"url": "<snapshot_url>"}'       \
    ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load/<snapshot_config_name>

For example:

$ curl                                      \
   --request POST                           \
   --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --data '{"url": "https://bucket.example.com/vault-snapshots/primary/paris-backup.snap"}' \
    ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load/paris-primary | jq

{
  "data": {
    "auto_config_name": "paris-primary",
    "cluster_id": "7430fa38-8fb6-4b35-b2a7-27ed4c831a44",
    "expires_at": "2025-07-16T03:24:42.867531+05:00",
    "snapshot_id": "9465df92-8236-4af9-8cc8-b7460d882e41",
    "url": "https://bucket.example.com/vault-snapshots/primary/paris-backup.snap",
    "status": "loading"
  }
}

Once you start a snapshot load, you can check the load status using the /sys/storage/raft/snapshot-load endpoint:

$ curl                                       \
   --request GET                             \
   --header "X-Vault-Token: ${VAULT_TOKEN}"  \
    ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load/<snapshot_id>

For example:

$ curl                                       \
   --request GET                             \
   --header "X-Vault-Token: ${VAULT_TOKEN}"  \
    ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load/9465df92-8236-4af9-8cc8-b7460d882e41

{
  "data": {
    "auto_config_name": "paris-primary",
    "cluster_id": "7430fa38-8fb6-4b35-b2a7-27ed4c831a44",
    "expires_at": "2025-07-16T03:24:42.867531+05:00",
    "snapshot_id": "9465df92-8236-4af9-8cc8-b7460d882e41",
    "url": "https://bucket.example.com/vault-snapshots/primary/paris-backup.snap",
    "status": "ready"
  }
}

Status key	Description
`loading`	Vault is in the process of loading the snapshot
`ready`	Loading completed successfully. You can read data from the snapshot.
`error`	Loading failed. Refer to the logs and error details for troubleshooting.

Step 2: Recover the secret

When the snapshot status is ready, you can recover the secret by specifying the snapshot ID and the secret path you want to read from.

Vault reads the secret at the specified path from the snapshot and writes that data to the associated path in Vault to recover the secret. The associated plugin then creates or updates the data at the specified path in live cluster storage.

Use vault read with the snapshot ID to read from the secret path and write the recovered data to the corresponding mount path on the Vault server:

$ vault read                    \
    -snapshot-id <snapshot_id>  \
    <mount_path>/<secret_path>

For example:

$ vault read                                            \
    -snapshot-id 9465df92-8236-4af9-8cc8-b7460d882e41s  \
    kv/data/telemetry-systems/api-key

Use the recover_snapshot_id query parameter and the snapshot ID to read from the secret path and write the recovered data to the corresponding mount path on the Vault server:

$ curl                                      \
   --request GET                            \
   --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/<mount_path>/data/<secret_path>?recover_snapshot_id=<snapshot_id>

For example, to recover secrets at telemetry-systems/api-key from a key/value plugin mounted at the default path, call the /kv/data/{secret_path} endpoint:

$ curl                                      \
   --request GET                            \
   --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/kv/data/telemetry-systems/api-key?recover_snapshot_id=9465df92-8236-4af9-8cc8-b7460d882e41

Step 3: Verify secret recovery

To verify secret recovery, read the secret from the expected path. For example, if you recovered a secret from a kv plugin at telemetry-systems/api-key:

$ vault kv get telemetry-systems/api-key

=== Data ===
Key    Value
---    -----
key    9C016BB3-F574-4A24-B8A7-8CE1F1CE2128

To verify secret recovery, read the secret from the expected path. For example, if you recovered secrets at telemetry-systems/api-key from a key/value plugin mounted at the default path, call the /kv/data/{secret_path} endpoint:

$ curl                                      \
   --request GET                            \
   --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/kv/data/telemetry-systems/api-key | jq

{
    "request_id": "689b2708-fe46-4ee6-0f1a-830f4d3acce0",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 2764800,
    "data": {
        "key": "9C016BB3-F574-4A24-B8A7-8CE1F1CE2128"
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null,
    "mount_type": "kv"
}