Skip to content

Commit 9b42318

Browse files
miagilepnerschavis
miagilepner
and
schavis
authored
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 <[email protected]> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <[email protected]> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <[email protected]> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <[email protected]> * Update website/content/api-docs/secret/kv/kv-v1.mdx Co-authored-by: Sarah Chavis <[email protected]> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <[email protected]> * Update website/content/docs/concepts/integrated-storage/snapshot-recover.mdx Co-authored-by: Sarah Chavis <[email protected]> * Update website/content/api-docs/secret/cubbyhole.mdx Co-authored-by: Sarah Chavis <[email protected]> * Update website/content/api-docs/secret/kv/kv-v1.mdx Co-authored-by: Sarah Chavis <[email protected]> * Update website/content/api-docs/secret/kv/kv-v1.mdx Co-authored-by: Sarah Chavis <[email protected]> * Apply suggestions from code review Co-authored-by: Sarah Chavis <[email protected]> * more fixes * remove example usage --------- Co-authored-by: Sarah Chavis <[email protected]>
1 parent 3701dcf commit 9b42318

File tree

15 files changed

+592
-27
lines changed

15 files changed

+592
-27
lines changed

‎changelog/30739.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
```release-note:feature
2+
**Secret Recovery from Snapshot (enterprise)**: Adds a framework to load an integrated storage
3+
snapshot into Vault and read, list, and recover KV v1 and cubbyhole secrets from the snapshot.
4+
```

‎website/content/api-docs/secret/cubbyhole.mdx‎

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,26 @@ This endpoint retrieves the secret at the specified location.
2727

2828
- `path` `(string: <required>)` – Specifies the path of the secret to read.
2929
This is specified as part of the URL.
30+
- `read_snapshot_id` `(string: <optional>)` - Query parameter specifing a loaded snapshot ID to
31+
read the secret.
3032

31-
### Sample request
33+
### Sample requests
3234

3335
```shell-session
3436
$ curl \
3537
--header "X-Vault-Token: ..." \
3638
http://127.0.0.1:8200/v1/cubbyhole/my-secret
3739
```
3840

41+
To read the secret from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
42+
43+
```shell-session
44+
$ curl \
45+
--header "X-Vault-Token: ..." \
46+
https://127.0.0.1:8200/v1/cubbyhole/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
47+
```
48+
49+
3950
### Sample response
4051

4152
```json
@@ -64,8 +75,9 @@ not return a value. The values themselves are not accessible via this command.
6475

6576
- `path` `(string: <required>)` – Specifies the path of the secrets to list.
6677
This is specified as part of the URL.
78+
- `read_snapshot_id` `(string: <optional>)` - Query parameter specifying the loaded snapshot ID from which Vault should read secrets for the provided path.
6779

68-
### Sample request
80+
### Sample requests
6981

7082
```shell-session
7183
$ curl \
@@ -74,6 +86,16 @@ $ curl \
7486
http://127.0.0.1:8200/v1/cubbyhole/my-secret
7587
```
7688

89+
To list the secrets from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
90+
91+
```shell-session
92+
$ curl \
93+
--header "X-Vault-Token: ..." \
94+
--request LIST \
95+
https://127.0.0.1:8200/v1/cubbyhole/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a"
96+
```
97+
98+
7799
### Sample response
78100

79101
The example below shows output for a query path of `cubbyhole/` when there are
@@ -128,6 +150,29 @@ $ curl \
128150
http://127.0.0.1:8200/v1/cubbyhole/my-secret
129151
```
130152

153+
## Recover secret
154+
155+
[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot.
156+
157+
| Method | Path |
158+
| :----- | :----------------- |
159+
| `POST` | `/cubbyhole/:path?recover_snapshot_id=:recover_snapshot_id` |
160+
161+
### Query parameters
162+
163+
- `path` `(string: <required>)` – The target path of the secrets you want to recover.
164+
- `recover_snapshot_id` `(string: <required>)` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
165+
166+
167+
### Sample request
168+
169+
```shell-session
170+
$ curl \
171+
--header "X-Vault-Token: ..." \
172+
--request POST \
173+
https://127.0.0.1:8200/v1/cubbyhole/my-secret?recover_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
174+
```
175+
131176
## Delete secret
132177

133178
This endpoint deletes the secret at the specified location.

‎website/content/api-docs/secret/kv/kv-v1.mdx‎

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,24 @@ This endpoint retrieves the secret at the specified location.
2828

2929
- `path` `(string: <required>)` – Specifies the path of the secret to read.
3030
This is specified as part of the URL.
31+
- `recover_snapshot_id` `(string: <required>)` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
3132

32-
### Sample request
33+
### Sample requests
3334

3435
```shell-session
3536
$ curl \
3637
--header "X-Vault-Token: ..." \
3738
https://127.0.0.1:8200/v1/secret/my-secret
3839
```
3940

41+
To read the secret from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
42+
43+
```shell-session
44+
$ curl \
45+
--header "X-Vault-Token: ..." \
46+
https://127.0.0.1:8200/v1/secret/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
47+
```
48+
4049
### Sample response
4150

4251
```json
@@ -74,8 +83,9 @@ this API.
7483

7584
- `path` `(string: <required>)` – Specifies the path of the secrets to list.
7685
This is specified as part of the URL.
86+
- `recover_snapshot_id` `(string: <required>)` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
7787

78-
### Sample request
88+
### Sample requests
7989

8090
```shell-session
8191
$ curl \
@@ -84,6 +94,16 @@ $ curl \
8494
https://127.0.0.1:8200/v1/secret/my-secret
8595
```
8696

97+
To list the secrets from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`:
98+
99+
```shell-session
100+
$ curl \
101+
--header "X-Vault-Token: ..." \
102+
--request LIST \
103+
https://127.0.0.1:8200/v1/secret/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a"
104+
```
105+
106+
87107
### Sample response
88108

89109
The example below shows output for a query path of `secret/` when there are
@@ -143,6 +163,28 @@ $ curl \
143163
https://127.0.0.1:8200/v1/secret/my-secret
144164
```
145165

166+
## Recover secret
167+
168+
[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot.
169+
170+
| Method | Path |
171+
| :----- | :------------------------------------------------------- |
172+
| `POST` | `/secret/:path?recover_snapshot_id=:recover_snapshot_id` |
173+
174+
### Query parameters
175+
176+
- `path` `(string: <required>)` – The target path of the secrets you want to recover.
177+
- `recover_snapshot_id` `(string: <required>)` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path.
178+
179+
### Sample request
180+
181+
```shell-session
182+
$ curl \
183+
--header "X-Vault-Token: ..." \
184+
--request POST \
185+
https://127.0.0.1:8200/v1/secret/my-secret?recover_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a
186+
```
187+
146188
## Delete secret
147189

148190
This endpoint deletes the secret at the specified location.

‎website/content/api-docs/system/storage/raftautosnapshots.mdx‎

Lines changed: 66 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ environment variables or files on disk in predefined locations.
6161
#### storage_type=local
6262

6363
- `local_max_space` `(integer: <required>)` - For `storage_type=local`, the maximum
64-
space, in bytes, to use for all snapshots with the given `file_prefix` in the `path_prefix` directory.
64+
space, in bytes, to use for all snapshots with the given `file_prefix` in the `path_prefix` directory.
6565
Snapshot attempts will fail if there is not enough
6666
space left in this allowance.
6767

@@ -278,8 +278,72 @@ $ curl \
278278
"last_snapshot_error": "",
279279
"last_snapshot_start": "2020-10-28T11:17:21-04:00",
280280
"last_snapshot_url": "file:///opt/vault/snapshots/vault-snapshot-1603898241699731000.snap",
281-
"snapshot_start": "2020-10-28T11:17:21-04:00",
281+
"snapshot_start": "2020-108T11:17:21-04:00",
282282
"snapshot_url": "file:///opt/vault/snapshots/vault-snapshot-1603898241699731000.snap"
283283
}
284284
}
285285
```
286+
287+
## Load a snapshot from an automated snapshot configuration
288+
289+
Load a new snapshot into the Vault cluster without overwriting the cluster with
290+
the snapshot's data. After loading a snapshot, you can recover, read, and list
291+
individual pieces of data from the loaded snapshot.
292+
293+
To manage the state of your loaded snapshot, use the [`/sys/storage/raft/snapshot-load`](/vault/api-docs/system/storage/raftsnapshotload)
294+
endpoints.
295+
296+
@include 'recover/loadedsnapshots.mdx'
297+
298+
<Note>
299+
300+
You cannot load a snapshot from an automated snapshot configuration with `storage_type=local`.
301+
Instead, upload the snapshot file using the
302+
[`/sys/storage/raft/snapshot-load`](/vault/api-docs/system/storage/raftsnapshotload) endpoint.
303+
304+
</Note>
305+
306+
| Method | Path |
307+
| :----- | :---------------------------------------------------- |
308+
| `POST` | `/sys/storage/raft/snapshot-auto/snapshot-load/:name` |
309+
310+
311+
### Parameters
312+
313+
- `name` `(string: <required>)` – Name of the configuration that created the snapshot.
314+
315+
- `url` `(string: <required>)` - The snapshot URL to load as returned by the
316+
`status` endpoint.
317+
318+
### Sample payload
319+
```json
320+
{
321+
"url": "https://example.com/raft.snap"
322+
}
323+
```
324+
325+
### Sample request
326+
327+
```shell-session
328+
$ curl \
329+
--header "X-Vault-Token: ..." \
330+
--request POST \
331+
--data @payload.json \
332+
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/snapshot-load/config1
333+
```
334+
335+
### Sample response
336+
337+
```json
338+
{
339+
"data": {
340+
"auto_config_name": "config1",
341+
"cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8",
342+
"expires_at": "2025-05-25T15:07:58.187769+01:00",
343+
"snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a",
344+
"url": "https://example.com/raft.snap",
345+
"status": "ready"
346+
}
347+
}
348+
```
349+

‎website/content/api-docs/system/storage/raftsnapshotload.mdx‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
layout: api
3+
page_title: /sys/storage/raft/snapshot-load - HTTP API
4+
description: |-
5+
6+
Use the snapshot-load endpoints to load a snapshot into your Vault cluster
7+
to recover individual pieces of data from the snapshot.
8+
---
9+
10+
# `/sys/storage/raft/snapshot-load`
11+
12+
@include 'alerts/enterprise-only.mdx'
13+
14+
Manage the state of loaded snapshots within the Vault cluster.
15+
16+
## Load a snapshot into Vault
17+
18+
19+
| Method | Path |
20+
| :----- | :--------------------------------------------- |
21+
| `POST` | `/sys/storage/raft/snapshot-load` |
22+
23+
Load a new snapshot into the Vault cluster without overwriting the cluster with
24+
the snapshot's data. After loading a snapshot, you can recover, read, and list
25+
individual pieces of data from the loaded snapshot.
26+
27+
@include 'recover/loadedsnapshots.mdx'
28+
29+
### Sample request
30+
31+
```shell-session
32+
$ curl \
33+
--header "X-Vault-Token: ..." \
34+
--request POST \
35+
--data-binary @raft.snap \
36+
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load
37+
```
38+
39+
40+
### Sample response
41+
42+
```json
43+
{
44+
"data": {
45+
"cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8",
46+
"expires_at": "2025-05-25T15:07:58.187769+01:00",
47+
"snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a",
48+
"status": "loading"
49+
}
50+
}
51+
```
52+
53+
## List loaded snapshots
54+
55+
List all snapshots currently loaded in the cluster.
56+
57+
| Method | Path |
58+
| :----- | :--------------------------------------- |
59+
| `LIST` | `/sys/storage/raft/snapshot-load` |
60+
61+
### Sample request
62+
63+
```shell-session
64+
$ curl \
65+
--header "X-Vault-Token: ..." \
66+
--request LIST \
67+
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load
68+
```
69+
70+
### Sample response
71+
72+
```json
73+
{
74+
"data": {
75+
"keys": ["2403d301-94f2-46a1-a39d-02be83e2831a"]
76+
}
77+
}
78+
```
79+
80+
## Read loaded snapshot
81+
82+
Read the status details of a given snapshot loaded in the cluster.
83+
84+
| Method | Path |
85+
| :----- | :--------------------------------------------- |
86+
| `GET` | `/sys/storage/raft/snapshot-load/:snapshot_id` |
87+
88+
### Sample request
89+
90+
```shell-session
91+
$ curl \
92+
--header "X-Vault-Token: ..." \
93+
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load/2403d301-94f2-46a1-a39d-02be83e2831a
94+
```
95+
96+
### Sample responses
97+
98+
For a snapshot loaded as a binary file:
99+
100+
```json
101+
{
102+
"data": {
103+
"cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8",
104+
"expires_at": "2025-05-25T15:07:58.187769+01:00",
105+
"snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a",
106+
"status": "ready"
107+
}
108+
}
109+
```
110+
111+
For a snapshot loaded from a an Automated Snapshot configuration:
112+
113+
```json
114+
{
115+
"data": {
116+
"auto_config_name": "config1",
117+
"cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8",
118+
"expires_at": "2025-05-25T15:07:58.187769+01:00",
119+
"snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a",
120+
"url": "https://example.com/raft.snap",
121+
"status": "ready"
122+
}
123+
}
124+
```
125+
126+
## Unload loaded snapshot
127+
128+
Unloads a currently loaded snapshot from the cluster.
129+
130+
| Method | Path |
131+
| :------- | :--------------------------------------------- |
132+
| `DELETE` | `/sys/storage/raft/snapshot-load/:snapshot_id` |
133+
134+
### Sample request
135+
136+
```shell-session
137+
$ curl \
138+
--header "X-Vault-Token: ..." \
139+
--request DELETE \
140+
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load/2403d301-94f2-46a1-a39d-02be83e2831a
141+
```

0 commit comments

Comments
 (0)