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 re-enable the same plugin at the same path, Vault treats it as a new mount with different internal identifiers and cannot associate the re-enabled 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.
The cluster must have mlock disabled.
The cluster cannot have another 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	Min Vault version
cubbyhole	`/:secret_name`	`recover`, `read`, `list`	1.20.0
kv (v1)	`/:secret_name`	`recover`, `read`, `list`	1.20.0
ssh	`/config/ca`	`recover`, `read`	1.20.3
databases	`/static-roles/:role_name`	`recover`, `read`, `list`	1.20.4
databases	`/static-creds/:role_name`	`read`	1.20.4

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 perform snapshot operations on shared paths.

Snapshot load and unload operations are restricted to the root namespace. All other snapshot operations can be performed in other namespaces.

Open the Vault GUI and sign in to the root namespace. While you can perform other snapshot operations from any namespace, you must perform load and unload operations under the root namespace.
Select Secrets Recovery from the left navigation menu.
Select Upload snapshot.
Select your upload method. To use an automated snapshot you must provide an automated snapshot config.
Click Load snapshot to complete the upload.
Monitor the upload until the status says "Ready" and the expiration date populates.
Click "View details → to open the snapshot details view

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-auto/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-auto/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-auto/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.

Use an autoloaded snapshot

If you configured automated snapshots with autoloading enabled, Vault Enterprise will automatically load a snapshot when the cluster starts and keep updating the loaded snapshot as new automated snapshots are created.

You can check for a loaded snapshot by listing the loaded snapshots:

Loaded snapshot card emphasized

Select Secrets Recovery from the navigation menu to view currently loaded snapshots.

You can check to see if there is a snapshot currently loaded by using vault list and the /sys/storage/raft/snapshot-load endpoint:

$ vault list /sys/storage/raft/snapshot-load

For example:

$ vault list /sys/storage/raft/snapshot-load

Keys
---- 
9465df92-8236-4af9-8cc8-b7460d882e41

You can check to see if there is a snapshot currently loaded by querying the /sys/storage/raft/snapshot-load endpoint:

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

For example:

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

{
  "data": {
    "keys": [
      "9465df92-8236-4af9-8cc8-b7460d882e41"
    ] 
  }
}

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.

Snapshot read and recover form fields

Use the available selectors and input fields to find the secret you want to read or recover. Once you selected, you can:

view the snapshot data as key/value pairs or as a JSON object
recover to the original resource path
recover the original resource to a new path

Use vault recover 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 recover                 \
    -snapshot-id <snapshot_id>  \
    <mount_path>/<secret_path>

For example:

```shell-session
$ vault recover                                     \
-snapshot-id 9465df92-8236-4af9-8cc8-b7460d882e41s  \
kv/telemetry-systems/api-key
```

You can also recover data to a different path than the original path in the snapshot, so long as both paths are on the same mount. Use the -from flag to specify the original path of the data in the snapshot:

$ vault recover                           \
    -snapshot-id <snapshot_id>            \
    -from <mount_path>/<old_secret_path>  \
    <mount_path>/<new_secret_path>

For example, to recover secrets at telemetry-systems/api-key from a key/value version 1 plugin mounted at the default path, but write the recovered data to telemetry-systems/api-key-recovered:

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

Tip

If you cannot use the explicit RECOVER HTTP method, you can also use PUT or POST for recover operations if you include the X-Vault-Recover-Snapshot-Id header and set it to the relevant snapshot ID.

Use the X-Vault-Recover-Snapshot-Id header 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 RECOVER                                      \
   --header "X-Vault-Token: ${VAULT_TOKEN}"               \
   --header "X-Vault-Recover-Snapshot-Id: <snapshot_id>"  \
    ${VAULT_ADDR}/v1/<mount_path>/<secret_path>

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

$ curl                                                                           \
    --request RECOVER                                                            \
    --header "X-Vault-Token: ${VAULT_TOKEN}"                                     \
    --header "X-Vault-Recover-Snapshot-Id: 9465df92-8236-4af9-8cc8-b7460d882e41" \
    ${VAULT_ADDR}/v1/kv/telemetry-systems/api-key

You can also recover data to a different path than the original path in the snapshot, so long as both paths are on the same mount. Use the X-Vault-Recover-Source-Path header to specify the original path of the data in the snapshot:

$ curl                                                                     \ 
   --request RECOVER                                                       \
   --header "X-Vault-Token: ${VAULT_TOKEN}"                                \
   --header "X-Vault-Recover-Snapshot-Id: <snapshot_id>"                   \
   --header "X-Vault-Recover-Source-Path: <mount_path>/<old_secret_path>"  \
     ${VAULT_ADDR}/v1/<mount_path>/<new_secret_path>

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

$ curl                                                                            \
    --request RECOVER                                                             \
    --header "X-Vault-Token: ${VAULT_TOKEN}"                                      \
    --header "X-Vault-Recover-Snapshot-Id: 9465df92-8236-4af9-8cc8-b7460d882e41"  \
    --header "X-Vault-Recover-Source-Path: kv/telemetry-systems/api-key"          \
    ${VAULT_ADDR}/v1/kv/telemetry-systems/api-key-recovered

Step 3: Verify secret recovery

If the recovery operation succeeds, the GUI displays a success message with a link to the recovered resource. Snapshot recovery operation

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 version 1 plugin mounted at the default path, call the /kv/{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"
}