VAULT-34525: Documentation for single item recovery from IS snapshot

changelog/30739.txt

@@ -0,0 +1,4 @@
+```release-note:feature
+**Item Recovery from Snapshot (enterprise)**: Adds the ability to load an integrated storage 
+snapshot into Vault and read, list, and recover single items from the snapshot.
+```

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

@@ -27,15 +27,26 @@ 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>)` - Specifies a loaded snapshot ID to
+read the secret. This is specified as a query parameter.
 
-### Sample request
+### Sample requests
 
 ```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     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,10 @@ 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>)` - Specifies a loaded snapshot ID from
+which to list the secrets at this path. This is specified as a query parameter.
 
-### Sample request
+### Sample requests
 
 ```shell-session
 $ curl \
@@ -74,6 +87,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 +151,31 @@ $ curl \
     http://127.0.0.1:8200/v1/cubbyhole/my-secret
 ```
 
+## Recover secret
+
+This endpoint [recovers](/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` |
+
+### Parameters
+
+- `path` `(string: <required>)` – Specifies the path of the secrets to
+create/update. This is specified as part of the URL.
+- `recover_snapshot_id` `(string: <required>)` - Specifies a loaded snapshot ID from
+which to recover the secret at this path. This is specified as a query parameter.
+
+
+### 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.

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

@@ -28,15 +28,25 @@ 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>)` - Specifies a loaded snapshot ID from
+  which to read the secret. This is specified as a query parameter.
 
-### Sample request
+### Sample requests
 
 ```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     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 +84,10 @@ this API.
 
 - `path` `(string: <required>)` – Specifies the path of the secrets to list.
   This is specified as part of the URL.
+- `read_snapshot_id` `(string: <optional>)` - Specifies a loaded snapshot ID from
+which to list the secrets at this path. This is specified as a query parameter.
 
-### Sample request
+### Sample requests
 
 ```shell-session
 $ curl \
@@ -84,6 +96,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 +165,30 @@ $ curl \
     https://127.0.0.1:8200/v1/secret/my-secret
 ```
 
+## Recover secret
+
+This endpoint [recovers](/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` |
+
+### Parameters
+
+- `path` `(string: <required>)` – Specifies the path of the secrets to
+create/update. This is specified as part of the URL.
+- `recover_snapshot_id` `(string: <required>)` - Specifies a loaded snapshot ID from
+which to recover the secret at this path. This is specified as a query parameter.
+
+### 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.

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

@@ -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,70 @@ $ 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 restoring the cluster to the
+snapshot's state. After you load a snapshot, you can recover, read, and list
+individual pieces of data from the loaded snapshot.
+
+After you load a snapshot, you can use the [`/sys/storage/raft/snapshot-load`](/vault/api-docs/system/storage/raftsnapshotload)
+endpoints to manage its state.
+
+@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. This is the URL 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"
+  }
+}
+```
+