mirror of
https://github.com/hashicorp/vault.git
synced 2026-05-05 20:36:26 +02:00
VAULT-34525: Documentation for single item recovery from IS snapshot (#30739)
* start * docs * everything except the concept doc * actual progress * thank you copilot for finding passive voice * formatting * add changelog * fix formatting of changelog * update changelog * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/secret/kv/kv-v1.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/docs/concepts/integrated-storage/snapshot-recover.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/secret/kv/kv-v1.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/secret/kv/kv-v1.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * more fixes * remove example usage --------- Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
This commit is contained in:
miagilepner
GitHub
parent
3701dcf3ca
commit
9b42318e44
4
changelog/30739.txt
Normal file
4
changelog/30739.txt
Normal file
@ -0,0 +1,4 @@
|
||||
```release-note:feature
|
||||
**Secret Recovery from Snapshot (enterprise)**: Adds a framework to load an integrated storage
|
||||
snapshot into Vault and read, list, and recover KV v1 and cubbyhole secrets from the snapshot.
|
||||
```
|
||||
@ -27,8 +27,10 @@ This endpoint retrieves the secret at the specified location.
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path of the secret to read.
|
||||
This is specified as part of the URL.
|
||||
- `read_snapshot_id` `(string: <optional>)` - Query parameter specifing a loaded snapshot ID to
|
||||
read the secret.
|
||||
|
||||
### Sample request
|
||||
### Sample requests
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
@ -36,6 +38,15 @@ $ curl \
|
||||
http://127.0.0.1:8200/v1/cubbyhole/my-secret
|
||||
```
|
||||
|
||||
To read the secret from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://127.0.0.1:8200/v1/cubbyhole/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
|
||||
```
|
||||
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
@ -64,8 +75,9 @@ not return a value. The values themselves are not accessible via this command.
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path of the secrets to list.
|
||||
This is specified as part of the URL.
|
||||
- `read_snapshot_id` `(string: <optional>)` - Query parameter specifying the loaded snapshot ID from which Vault should read secrets for the provided path.
|
||||
|
||||
### Sample request
|
||||
### Sample requests
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
@ -74,6 +86,16 @@ $ curl \
|
||||
http://127.0.0.1:8200/v1/cubbyhole/my-secret
|
||||
```
|
||||
|
||||
To list the secrets from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request LIST \
|
||||
https://127.0.0.1:8200/v1/cubbyhole/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a"
|
||||
```
|
||||
|
||||
|
||||
### Sample response
|
||||
|
||||
The example below shows output for a query path of `cubbyhole/` when there are
|
||||
@ -128,6 +150,29 @@ $ curl \
|
||||
http://127.0.0.1:8200/v1/cubbyhole/my-secret
|
||||
```
|
||||
|
||||
## Recover secret
|
||||
|
||||
[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :----------------- |
|
||||
| `POST` | `/cubbyhole/:path?recover_snapshot_id=:recover_snapshot_id` |
|
||||
|
||||
### Query parameters
|
||||
|
||||
- `path` `(string: <required>)` – The target path of the secrets you want to recover.
|
||||
- `recover_snapshot_id` `(string: <required>)` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
|
||||
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
https://127.0.0.1:8200/v1/cubbyhole/my-secret?recover_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
|
||||
```
|
||||
|
||||
## Delete secret
|
||||
|
||||
This endpoint deletes the secret at the specified location.
|
||||
|
||||
@ -28,8 +28,9 @@ This endpoint retrieves the secret at the specified location.
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path of the secret to read.
|
||||
This is specified as part of the URL.
|
||||
- `recover_snapshot_id` `(string: <required>)` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
|
||||
|
||||
### Sample request
|
||||
### Sample requests
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
@ -37,6 +38,14 @@ $ curl \
|
||||
https://127.0.0.1:8200/v1/secret/my-secret
|
||||
```
|
||||
|
||||
To read the secret from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://127.0.0.1:8200/v1/secret/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
@ -74,8 +83,9 @@ this API.
|
||||
|
||||
- `path` `(string: <required>)` – Specifies the path of the secrets to list.
|
||||
This is specified as part of the URL.
|
||||
- `recover_snapshot_id` `(string: <required>)` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
|
||||
|
||||
### Sample request
|
||||
### Sample requests
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
@ -84,6 +94,16 @@ $ curl \
|
||||
https://127.0.0.1:8200/v1/secret/my-secret
|
||||
```
|
||||
|
||||
To list the secrets from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request LIST \
|
||||
https://127.0.0.1:8200/v1/secret/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a"
|
||||
```
|
||||
|
||||
|
||||
### Sample response
|
||||
|
||||
The example below shows output for a query path of `secret/` when there are
|
||||
@ -143,6 +163,28 @@ $ curl \
|
||||
https://127.0.0.1:8200/v1/secret/my-secret
|
||||
```
|
||||
|
||||
## Recover secret
|
||||
|
||||
[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :------------------------------------------------------- |
|
||||
| `POST` | `/secret/:path?recover_snapshot_id=:recover_snapshot_id` |
|
||||
|
||||
### Query parameters
|
||||
|
||||
- `path` `(string: <required>)` – The target path of the secrets you want to recover.
|
||||
- `recover_snapshot_id` `(string: <required>)` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
https://127.0.0.1:8200/v1/secret/my-secret?recover_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
|
||||
```
|
||||
|
||||
## Delete secret
|
||||
|
||||
This endpoint deletes the secret at the specified location.
|
||||
|
||||
@ -61,7 +61,7 @@ environment variables or files on disk in predefined locations.
|
||||
#### storage_type=local
|
||||
|
||||
- `local_max_space` `(integer: <required>)` - For `storage_type=local`, the maximum
|
||||
space, in bytes, to use for all snapshots with the given `file_prefix` in the `path_prefix` directory.
|
||||
space, in bytes, to use for all snapshots with the given `file_prefix` in the `path_prefix` directory.
|
||||
Snapshot attempts will fail if there is not enough
|
||||
space left in this allowance.
|
||||
|
||||
@ -278,8 +278,72 @@ $ curl \
|
||||
"last_snapshot_error": "",
|
||||
"last_snapshot_start": "2020-10-28T11:17:21-04:00",
|
||||
"last_snapshot_url": "file:///opt/vault/snapshots/vault-snapshot-1603898241699731000.snap",
|
||||
"snapshot_start": "2020-10-28T11:17:21-04:00",
|
||||
"snapshot_start": "2020-108T11:17:21-04:00",
|
||||
"snapshot_url": "file:///opt/vault/snapshots/vault-snapshot-1603898241699731000.snap"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Load a snapshot from an automated snapshot configuration
|
||||
|
||||
Load a new snapshot into the Vault cluster without overwriting the cluster with
|
||||
the snapshot's data. After loading a snapshot, you can recover, read, and list
|
||||
individual pieces of data from the loaded snapshot.
|
||||
|
||||
To manage the state of your loaded snapshot, use the [`/sys/storage/raft/snapshot-load`](/vault/api-docs/system/storage/raftsnapshotload)
|
||||
endpoints.
|
||||
|
||||
@include 'recover/loadedsnapshots.mdx'
|
||||
|
||||
<Note>
|
||||
|
||||
You cannot load a snapshot from an automated snapshot configuration with `storage_type=local`.
|
||||
Instead, upload the snapshot file using the
|
||||
[`/sys/storage/raft/snapshot-load`](/vault/api-docs/system/storage/raftsnapshotload) endpoint.
|
||||
|
||||
</Note>
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :---------------------------------------------------- |
|
||||
| `POST` | `/sys/storage/raft/snapshot-auto/snapshot-load/:name` |
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the configuration that created the snapshot.
|
||||
|
||||
- `url` `(string: <required>)` - The snapshot URL to load as returned by the
|
||||
`status` endpoint.
|
||||
|
||||
### Sample payload
|
||||
```json
|
||||
{
|
||||
"url": "https://example.com/raft.snap"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/snapshot-load/config1
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"auto_config_name": "config1",
|
||||
"cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8",
|
||||
"expires_at": "2025-05-25T15:07:58.187769+01:00",
|
||||
"snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a",
|
||||
"url": "https://example.com/raft.snap",
|
||||
"status": "ready"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
141
website/content/api-docs/system/storage/raftsnapshotload.mdx
Normal file
141
website/content/api-docs/system/storage/raftsnapshotload.mdx
Normal file
@ -0,0 +1,141 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: /sys/storage/raft/snapshot-load - HTTP API
|
||||
description: |-
|
||||
|
||||
Use the snapshot-load endpoints to load a snapshot into your Vault cluster
|
||||
to recover individual pieces of data from the snapshot.
|
||||
---
|
||||
|
||||
# `/sys/storage/raft/snapshot-load`
|
||||
|
||||
@include 'alerts/enterprise-only.mdx'
|
||||
|
||||
Manage the state of loaded snapshots within the Vault cluster.
|
||||
|
||||
## Load a snapshot into Vault
|
||||
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :--------------------------------------------- |
|
||||
| `POST` | `/sys/storage/raft/snapshot-load` |
|
||||
|
||||
Load a new snapshot into the Vault cluster without overwriting the cluster with
|
||||
the snapshot's data. After loading a snapshot, you can recover, read, and list
|
||||
individual pieces of data from the loaded snapshot.
|
||||
|
||||
@include 'recover/loadedsnapshots.mdx'
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data-binary @raft.snap \
|
||||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load
|
||||
```
|
||||
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8",
|
||||
"expires_at": "2025-05-25T15:07:58.187769+01:00",
|
||||
"snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a",
|
||||
"status": "loading"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## List loaded snapshots
|
||||
|
||||
List all snapshots currently loaded in the cluster.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :--------------------------------------- |
|
||||
| `LIST` | `/sys/storage/raft/snapshot-load` |
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request LIST \
|
||||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"keys": ["2403d301-94f2-46a1-a39d-02be83e2831a"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Read loaded snapshot
|
||||
|
||||
Read the status details of a given snapshot loaded in the cluster.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :--------------------------------------------- |
|
||||
| `GET` | `/sys/storage/raft/snapshot-load/:snapshot_id` |
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load/2403d301-94f2-46a1-a39d-02be83e2831a
|
||||
```
|
||||
|
||||
### Sample responses
|
||||
|
||||
For a snapshot loaded as a binary file:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8",
|
||||
"expires_at": "2025-05-25T15:07:58.187769+01:00",
|
||||
"snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a",
|
||||
"status": "ready"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For a snapshot loaded from a an Automated Snapshot configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"auto_config_name": "config1",
|
||||
"cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8",
|
||||
"expires_at": "2025-05-25T15:07:58.187769+01:00",
|
||||
"snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a",
|
||||
"url": "https://example.com/raft.snap",
|
||||
"status": "ready"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Unload loaded snapshot
|
||||
|
||||
Unloads a currently loaded snapshot from the cluster.
|
||||
|
||||
| Method | Path |
|
||||
| :------- | :--------------------------------------------- |
|
||||
| `DELETE` | `/sys/storage/raft/snapshot-load/:snapshot_id` |
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load/2403d301-94f2-46a1-a39d-02be83e2831a
|
||||
```
|
||||
@ -21,5 +21,9 @@ $ vault list identity/entity/id
|
||||
|
||||
## Usage
|
||||
|
||||
There are no flags beyond the [standard set of flags](/vault/docs/commands)
|
||||
included on all commands.
|
||||
The following flag is available in addition to the [standard set of
|
||||
flags](/vault/docs/commands) included on all commands.
|
||||
|
||||
### Command options
|
||||
|
||||
- `snapshot-id` `(string: "")` - The ID of raft snapshot previously loaded into the cluster that you want to list data from.
|
||||
|
||||
@ -158,34 +158,77 @@ Usage: vault operator raft remove-peer <server_id>
|
||||
## snapshot
|
||||
|
||||
This command groups subcommands for operators interacting with the snapshot
|
||||
functionality of the integrated Raft storage backend. There are 2 subcommands
|
||||
supported: `save` and `restore`.
|
||||
functionality of the integrated Raft storage backend.
|
||||
|
||||
```text
|
||||
Usage: vault operator raft snapshot <subcommand> [options] [args]
|
||||
|
||||
This command groups subcommands for operators interacting with the snapshot
|
||||
functionality of the integrated Raft storage backend.
|
||||
functionality of the integrated Raft storage backend. Here are a few examples of
|
||||
the Raft snapshot operator commands:
|
||||
|
||||
Installs the provided snapshot, returning the cluster to the state defined in it:
|
||||
|
||||
$ vault operator raft snapshot restore raft.snap
|
||||
|
||||
Saves a snapshot of the current state of the Raft cluster into a file:
|
||||
|
||||
$ vault operator raft snapshot save raft.snap
|
||||
|
||||
Inspects a snapshot based on a file:
|
||||
|
||||
$ vault operator raft snapshot inspect raft.snap
|
||||
|
||||
Please see the individual subcommand help for detailed usage information.
|
||||
|
||||
Subcommands:
|
||||
inspect Inspects raft snapshot
|
||||
load Loads the provided local or cloud storage snapshot
|
||||
restore Installs the provided snapshot, returning the cluster to the state defined in it
|
||||
save Saves a snapshot of the current state of the Raft cluster into a file
|
||||
unload Unloads the snapshot with provided ID```
|
||||
```
|
||||
|
||||
### snapshot save
|
||||
### snapshot inspect
|
||||
|
||||
Takes a snapshot of the Vault data. The snapshot can be used to restore Vault to
|
||||
the point in time when a snapshot was taken.
|
||||
Inspects a snapshot file taken from a Vault raft cluster and prints a table showing the number of keys and the amount of space used.
|
||||
|
||||
```text
|
||||
Usage: vault operator raft snapshot save <snapshot_file>
|
||||
|
||||
Saves a snapshot of the current state of the Raft cluster into a file.
|
||||
|
||||
$ vault operator raft snapshot save raft.snap
|
||||
Usage: vault operator raft snapshot inspect <snapshot_file>
|
||||
```
|
||||
|
||||
~> **Note:** Snapshot is not supported when Raft is used only for `ha_storage`.
|
||||
For example:
|
||||
|
||||
```shell-session
|
||||
$ vault operator raft snapshot inspect raft.snap
|
||||
```
|
||||
|
||||
### snapshot load
|
||||
|
||||
@include 'alerts/enterprise-only.mdx'
|
||||
|
||||
Load a new snapshot into the Vault cluster without overwriting the cluster with
|
||||
the snapshot's data.
|
||||
|
||||
@include 'recover/loadedsnapshots.mdx'
|
||||
|
||||
```text
|
||||
Usage: vault operator raft snapshot load < SNAPSHOT_FILE | auto_snapshot_config=CONFIG_NAME url=URL >
|
||||
|
||||
Loads the provided snapshot for reading or recovering data on supported paths.
|
||||
|
||||
This command supports two modes of operation:
|
||||
|
||||
1. Loading a local snapshot file from the filesystem.
|
||||
In this mode, the file path must be provided as the only positional argument.
|
||||
|
||||
$ vault operator raft snapshot load raft.snap
|
||||
|
||||
2. Loading a snapshot that was created by Vault's automated snapshot utility from cloud storage.
|
||||
In this case, the command accepts two K=V arguments: auto_snapshot_config and url.
|
||||
|
||||
$ vault operator raft snapshot load auto_snapshot_config=foo url=https://foo.com/blob/snapshot
|
||||
```
|
||||
|
||||
### snapshot restore
|
||||
|
||||
@ -199,18 +242,34 @@ Usage: vault operator raft snapshot restore <snapshot_file>
|
||||
$ vault operator raft snapshot restore raft.snap
|
||||
```
|
||||
|
||||
### snapshot inspect
|
||||
### snapshot save
|
||||
|
||||
Inspects a snapshot file taken from a Vault Raft cluster and prints a table showing the number of keys and the amount of space used.
|
||||
Takes a snapshot of your Vault data. You can use the snapshot to restore Vault
|
||||
to the point in time when you took the snapshot if you use integrated storage.
|
||||
Vault does not support snapshots for deployments that only use raft for
|
||||
high-availability storage.
|
||||
|
||||
```text
|
||||
Usage: vault operator raft snapshot inspect <snapshot_file>
|
||||
Usage: vault operator raft snapshot save <snapshot_file>
|
||||
|
||||
Saves a snapshot of the current state of the Raft cluster into a file.
|
||||
|
||||
$ vault operator raft snapshot save raft.snap
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```shell-session
|
||||
$ vault operator raft snapshot inspect raft.snap
|
||||
### snapshot unload
|
||||
|
||||
@include 'alerts/enterprise-only.mdx'
|
||||
|
||||
Unload a snapshot previously loaded with `vault operator raft snapshot load`.
|
||||
|
||||
```text
|
||||
Usage: vault operator raft snapshot unload <SNAPSHOT_ID>
|
||||
|
||||
Unloads the snapshot with the provided ID.
|
||||
|
||||
$ vault operator raft snapshot unload 8a4f31cc-7bb2-227a-aa18-8f140fb40f10
|
||||
```
|
||||
|
||||
## autopilot
|
||||
|
||||
@ -63,6 +63,10 @@ engine, it prints the output in more structured format that is easy to read.
|
||||
The following flags are available in addition to the [standard set of
|
||||
flags](/vault/docs/commands) included on all commands.
|
||||
|
||||
### Command options
|
||||
|
||||
- `snapshot-id` `(string: "")` - Specifies a loaded snapshot ID to read the data from.
|
||||
|
||||
### Output options
|
||||
|
||||
- `-field` `(string: "")` - Print only the field with the given name, in the format
|
||||
|
||||
34
website/content/docs/commands/recover.mdx
Normal file
34
website/content/docs/commands/recover.mdx
Normal file
@ -0,0 +1,34 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: recover - Command
|
||||
description: |-
|
||||
Use the recover command to pull data from a loaded snapshot and restore it at
|
||||
the specified path.
|
||||
---
|
||||
|
||||
# recover
|
||||
|
||||
@include 'alerts/enterprise-only.mdx'
|
||||
|
||||
The `recover` command pulls data at the specified path from a loaded snapshot
|
||||
and restores it to the cluster, overwriting newer data on the same path.
|
||||
|
||||
@include 'recover/deletedmounts.mdx'
|
||||
|
||||
## Examples
|
||||
|
||||
Recover the KV version 1 secret at the path `my-secret` from the loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
|
||||
|
||||
```shell-session
|
||||
$ vault recover -snapshot-id=2403d301-94f2-46a1-a39d-02be83e2831a secret/my-secret
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
The following flag is available in addition to the [standard set of
|
||||
flags](/vault/docs/commands) included on all commands.
|
||||
|
||||
### Command options
|
||||
|
||||
- `snapshot-id` `(string: "")` - Specifies a loaded snapshot ID to recover
|
||||
the data from.
|
||||
@ -0,0 +1,126 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Item recovery from a snapshot
|
||||
description: >-
|
||||
Use item recovery to restore specific data from a snapshot rather than
|
||||
restoring the entire snapshot.
|
||||
---
|
||||
|
||||
# Item recovery from a snapshot
|
||||
|
||||
@include 'alerts/enterprise-only.mdx'
|
||||
|
||||
## Overview
|
||||
|
||||
With Vault Enterprise you can recover individual items from an integrated
|
||||
storage snapshot without needing to restore your entire cluster to the state in
|
||||
the snapshot.
|
||||
|
||||
Item recovery is a two-step process:
|
||||
|
||||
1. Load a snapshot into Vault so Vault can access the data and assign a snapshot
|
||||
ID.
|
||||
1. Use that snapshot ID to read, list, and recover individual paths from the
|
||||
snapshot.
|
||||
|
||||
## Supported Paths
|
||||
|
||||
Not all paths support snapshot operations. The following paths are currently supported:
|
||||
|
||||
| Plugin | Path | Snapshot operations supported | Vault version |
|
||||
|-----------|-----------------|-------------------------------|---------------|
|
||||
| cubbyhole | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 |
|
||||
| kv (v1) | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 |
|
||||
|
||||
|
||||
|
||||
## Loading snapshots
|
||||
|
||||
Load a snapshot using the [`vault operator raft snapshot load`](/vault/docs/commands/operator/raft#snapshot-load) command. The
|
||||
snapshot can either be a file on disk or a snapshot created from Vault's
|
||||
[automated snapshot](/vault/docs/enterprise/automated-integrated-storage-snapshots) feature
|
||||
and stored in cloud storage.
|
||||
|
||||
Vault will return you information about the loaded snapshot, including a `snapshot_id`
|
||||
which you will reference to perform operations from the snapshot. Vault sets the
|
||||
initial status of the loaded snapshot to `loading`, indicating that it is extracting
|
||||
the data within the snapshot and preparing it for use. Once Vault fully loads the
|
||||
snapshot, it updates the status to `ready`. You can query your loaded snapshot at the API
|
||||
endpoint [`sys/storage/raft/snapshot-load/:snapshot_id`](/vault/api-docs/system/storage/raftsnapshotload#read-loaded-snapshot).
|
||||
|
||||
If something goes wrong during the loading process, Vault will set the status of
|
||||
the loaded snapshot to `error` and return a new field called `error` describing
|
||||
the problem. Snapshots with an `error` status cannot be used for any snapshot operations.
|
||||
|
||||
@include 'recover/loadedsnapshots.mdx'
|
||||
|
||||
### Replication
|
||||
|
||||
Performance primaries and performance secondaries can each load their own snapshots.
|
||||
However, a performance secondary will not be able to perform snapshot operations
|
||||
on any shared paths. Performance secondaries can only perform snapshot operations
|
||||
on paths corresponding to local mounts.
|
||||
|
||||
Disaster recovery secondaries cannot load snapshots.
|
||||
|
||||
## Snapshot operations
|
||||
|
||||
Once you have loaded a snapshot, you can specify the snapshot ID read, list, and
|
||||
recover operations.
|
||||
|
||||
To read a secret at a specific path from the snapshot:
|
||||
```shell
|
||||
$ vault read -snapshot-id <snapshot_id> secret/my-secret
|
||||
```
|
||||
|
||||
To list the secrets at a specific path from the snapshot:
|
||||
```shell
|
||||
$ vault list -snapshot-id <snapshot_id> secret/
|
||||
```
|
||||
Reading and listing use the same API endpoints as the normal read and list, but have
|
||||
an extra query parameter to specify the snapshot ID. Vault will perform the operation
|
||||
on the backend, but use the snapshot's stored data instead of the live data.
|
||||
|
||||
@include 'recover/deletedmounts.mdx'
|
||||
|
||||
To recover a secret at a specific path from the snapshot:
|
||||
```shell
|
||||
$ vault recover -snapshot-id <snapshot_id> secret/my-secret
|
||||
```
|
||||
|
||||
To perform a recover command, Vault will first read the secret at the path from
|
||||
the snapshot to retrieve the snapshot's version of the data. Then, Vault will send the
|
||||
data to the plugin backend to perform the recover operation. The plugin backend
|
||||
will use this data (along with potentially its own information) to create or update
|
||||
the data at the specified path in live storage.
|
||||
|
||||
## Policies
|
||||
|
||||
Reading and listing from a snapshot are guarded by the same `read` and `list`
|
||||
capabilities as the normal read and list operations. This means that if a user has
|
||||
`read` or `list` on the path, by default they will be allowed to read or list from a
|
||||
snapshot on that path.
|
||||
|
||||
If you would like to **disallow** reading or listing from a snapshot, you can
|
||||
create a policy that denies the `read_snapshot_id` parameter. For example, to
|
||||
disallow reading/listing from a snapshot on the `secrets/*` path, you can create
|
||||
the policy:
|
||||
|
||||
```hcl
|
||||
path "secrets/*" {
|
||||
capabilities = ["read", "list"]
|
||||
denied_parameters = {
|
||||
read_snapshot_id = []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Users must have the `recover` capability on a path to recover that path from a
|
||||
snapshot. The user does not need to have any other capabilities to allow
|
||||
this operation.
|
||||
|
||||
```hcl
|
||||
path "secrets/*" {
|
||||
capabilities = ["recover"]
|
||||
}
|
||||
```
|
||||
@ -104,7 +104,7 @@ Here is a more detailed policy, and it is documented inline:
|
||||
# This section grants all access on "secret/*". further restrictions can be
|
||||
# applied to this broad policy, as shown below.
|
||||
path "secret/*" {
|
||||
capabilities = ["create", "read", "update", "patch", "delete", "list"]
|
||||
capabilities = ["create", "read", "update", "patch", "delete", "list", "recover"]
|
||||
}
|
||||
|
||||
# Even though we allowed secret/*, this line explicitly denies
|
||||
@ -193,9 +193,9 @@ wildcard appears in the same place, both end in `*` and the latter has two wildc
|
||||
segments while the former has zero. So we end at rule (3), and give `"secret/+/+/foo/*"`
|
||||
_lower_ priority.
|
||||
|
||||
Another example utilizing Vault [namespaces](/vault/docs/enterprise/namespaces), given [nested](/vault/tutorials/enterprise/namespace-structure) namespaces `ns1/ns2/ns3` and two paths,
|
||||
Another example utilizing Vault [namespaces](/vault/docs/enterprise/namespaces), given [nested](/vault/tutorials/enterprise/namespace-structure) namespaces `ns1/ns2/ns3` and two paths,
|
||||
`"secret/*"` and `"ns1/ns2/ns3/secret/apps/*"` where `secret` is a mountpoint in namespace `ns3`. The first path is
|
||||
defined in a policy inside/relative to namespace `ns3` while the second path is defined in a policy in the `root` namespace.
|
||||
defined in a policy inside/relative to namespace `ns3` while the second path is defined in a policy in the `root` namespace.
|
||||
Both paths end in `*` but the first is shorter. So we end at rule (4), and give `"secret/*"` _lower_ priority.
|
||||
|
||||
!> **Informational:**The glob character referred to in this documentation is the asterisk (`*`).
|
||||
@ -258,6 +258,8 @@ HTTP verbs.
|
||||
- `subscribe` - Allows subscribing to [events](/vault/docs/concepts/events)
|
||||
for the given path.
|
||||
|
||||
- `recover` - Allows recovering the data on the given path from a snapshot
|
||||
|
||||
~> **Note:** Capabilities usually map to the HTTP verb, and not the underlying
|
||||
action taken. This can be a common source of confusion. Generating database
|
||||
credentials _creates_ database credentials, but the HTTP request is a GET which
|
||||
|
||||
10
website/content/partials/recover/deletedmounts.mdx
Normal file
10
website/content/partials/recover/deletedmounts.mdx
Normal file
@ -0,0 +1,10 @@
|
||||
<Note>
|
||||
|
||||
A path cannot be read, listed, or recovered from a snapshot if the path's
|
||||
mount has been disabled! Even if you later re-enable the same plugin at the
|
||||
same path, the underlying identifiers for the plugin will be different and
|
||||
Vault will not be able to find the underlying storage entries for the mount
|
||||
within the snapshot.
|
||||
|
||||
</Note>
|
||||
|
||||
13
website/content/partials/recover/loadedsnapshots.mdx
Normal file
13
website/content/partials/recover/loadedsnapshots.mdx
Normal file
@ -0,0 +1,13 @@
|
||||
<Note title="Restrictions for loading snapshots">
|
||||
|
||||
* The snapshot must be from the same cluster and have the same unseal keys as
|
||||
the current cluster.
|
||||
* You can only load one snapshot into a cluster at a time.
|
||||
* Vault automatically unloads snapshots 72 hours after they are loaded.
|
||||
* If your cluster's active node changes, the loaded snapshot's status updates
|
||||
to `error` and it cannot be used for any recover operations. You must unload and
|
||||
reload the snapshot to use it again.
|
||||
* You cannot load a snapshot if your cluster has
|
||||
[mlock](/vault/docs/configuration#disable_mlock) enabled in its Vault configuration.
|
||||
|
||||
</Note>
|
||||
@ -764,6 +764,10 @@
|
||||
{
|
||||
"title": "<code>/sys/storage/raft/snapshot-auto</code>",
|
||||
"path": "system/storage/raftautosnapshots"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/storage/raft/snapshot-load</code>",
|
||||
"path": "system/storage/raftsnapshotload"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@ -156,6 +156,15 @@
|
||||
"title": "Autopilot",
|
||||
"path": "concepts/integrated-storage/autopilot"
|
||||
},
|
||||
{
|
||||
"title": "Item Recovery",
|
||||
"path": "concepts/integrated-storage/snapshot-recover",
|
||||
"badge": {
|
||||
"text": "ENT",
|
||||
"type": "filled",
|
||||
"color": "neutral"
|
||||
}
|
||||
},
|
||||
{
|
||||
"title": "Migration checklist",
|
||||
"path": "concepts/integrated-storage/migration-checklist"
|
||||
@ -1515,6 +1524,10 @@
|
||||
"title": "<code>read</code>",
|
||||
"path": "commands/read"
|
||||
},
|
||||
{
|
||||
"title": "<code>recover</code>",
|
||||
"path": "commands/recover"
|
||||
},
|
||||
{
|
||||
"title": "<code>secrets</code>",
|
||||
"routes": [
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user