Snapshot Single Item Recovery Docs

content/vault/v1.21.x (rc)/content/docs/concepts/data-recovery/index.mdx

@@ -0,0 +1,208 @@
+---
+layout: docs
+page_title: 'Single Item Recovery'
+description: >-
+   Technical overview covering the concepts of snapshot management and data recovery
+  in Vault
+---
+
+# Single item recovery in Vault 
+
+When a secret is accidentally changed or deleted, Secret Recovery provides the ability 
+to restore specific supported items from a previously taken snapshot. This is a more 
+targeted and flexible operation than the alternative, restoring the entire cluster 
+from a snapshot, and is much safer to delegate to specific users.
+
+The **Secrets Recovery** page 
+in the Vault GUI provides the ability to load and unload snapshots to the cluster, 
+which can then be used in recovery operations. Supported resource types can then be 
+recovered or read from the snapshot via the GUI. (This provides the additional benefit of 
+allowing customers insight into what is contained within the snapshot, even if no 
+recovery operation is performed.) You can also use the Vault CLI or API to perform snapshot operations.
+
+**Supported resource types**: KV v1 secrets, Cubbyhole secrets, Database static roles  
+(please note: SSH keys are currently supported by the backend, but do not yet have frontend support)
+
+Automatic snapshot configurations can also be configured to automatically load the snapshot to Vault 
+itself, making it available for recovery. Snapshot management permissions are separate from recovery 
+permissions so that recovery operations can be delegated but controlled.
+
+Additionally, rather than recovering a previous version of a secret to the same path and 
+overwriting the current version of that secret, it is possible to “recover as a copy” and 
+restore the previous version to a new path, thus maintaining both.
+
+## Policy Examples
+1. Allow Snapshot Management 
+    ```hcl
+    path "sys/storage/raft/snapshot-load" {
+        capabilities = ["update"]
+    }
+    ```
+
+2. Allow Recovery
+    ```hcl
+    path "secrets/*" {
+        capabilities = ["recover"]
+    }
+    ```
+
+3. Restrict Read 
+    ```hcl
+    path "secrets/*" {
+        capabilities = ["read", "list"]
+        denied_parameters = {
+            read_snapshot_id = []
+        }
+    }
+    ```
+
+## Upload a snapshot
+
+Snapshots can be provided in the form of automated snapshots in cloud storage or manual snapshots 
+uploaded from a local file. Automated snapshots can be configured to auto load the snapshot to the cluster.
+
+
+<Tabs>
+<Tab heading="Web UI" group="ui">
+
+1. Open a web browser to access the Vault UI and sign in to the root namespace.
+   <Tip title="Namespace restriction">
+
+   Snapshot load and unload operations are restricted to the root namespace. All other snapshot operations 
+   can be performed in other namespaces. 
+
+    </Tip>
+
+    <Tip title="Permissions Required">
+        This requires snapshot management permissions.
+    </Tip>
+
+2. Select **Secrets Recovery** from the left navigation menu.
+
+3. Select **Upload snapshot**.
+    ![Load snapshot button location emphasized](/img/ui-secret-recovery-upload.png)
+
+4. Select the method of upload. If loading from **automated** snapshots, an automated snapshot config is required.
+Refer to the [automated snapshot API](https://developer.hashicorp.com/vault/api-docs/system/storage/raftautosnapshots#load-a-snapshot-from-an-automated-snapshot-configuration) 
+to learn more about automated snapshots.
+    ![Load snapshot form](/img/ui-secret-recovery-upload-form.png)
+
+5. Click **Load snapshot** to complete the upload.
+
+
+</Tab>
+<Tab heading="API call using cURL" group="api">
+
+@include 'alerts/restricted-root.mdx'
+
+**Example of an automated snapshot upload:**
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    --data @payload.json \
+     ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-auto/snapshot-load/${CONFIG_NAME}
+
+```
+
+Refer to the [automated snapshot API](https://developer.hashicorp.com/vault/api-docs/system/storage/raftautosnapshots#load-a-snapshot-from-an-automated-snapshot-configuration) 
+to learn more about automated snapshots.
+
+**Example of a manual upload:** 
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ${VAULT_TOKEN}" \
+    --request POST \
+    --data-binary @raft.snap \
+    ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load
+```
+
+</Tab>
+</Tabs>
+
+
+## Snapshot overview
+
+1. The status of the snapshot and the expiration date is shown. This also allows 
+to navigate to the snapshot details view.
+    ![Snapshot overview card with status and details link emphasized](/img/ui-secret-recovery-overview-details.png)
+2. Snapshot resources can be recovered or read from the snapshot overview page.
+While in the root namespace, a namespace selector will be shown 
+to allow for snapshot operations on resources in child namespaces as well.
+
+## Snapshot recovery
+
+<Tabs>
+<Tab heading="Web UI" group="ui">
+    <Tip title="Permissions Required">
+        This requires recover permissions specific to the resource.
+    </Tip>
+
+Upon a successful recovery operation, a success message with a link to the recovered resource will be shown.
+    ![Snapshot recovery operation](/img/ui-secret-recovery-recover-message.png)
+In addition to recovering to the original resource path, recovering a copy to a new path is possible. The original resource will be unaffected.
+    ![Snapshot recovery to copy operation](/img/ui-secret-recovery-recover-copy.png)
+</Tab>
+<Tab heading="API call using cURL" group="api">
+
+```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
+```
+
+</Tab>
+</Tabs>
+
+## Snapshot read
+
+<Tabs>
+<Tab heading="Web UI" group="ui">
+    <Tip title="Permissions Required">
+        This requires read permissions specific to the resource.
+    </Tip>
+
+Upon a successful read operation, the resource can be viewed as key value pairs or as JSON.
+![Snapshot read view in key value format](/img/ui-secret-recovery-read-kv.png)
+![Snapshot read view in JSON format](/img/ui-secret-recovery-read-json.png)
+
+</Tab>
+<Tab heading="API call using cURL" group="api">
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load/2403d301-94f2-46a1-a39d-02be83e2831a
+
+```
+
+</Tab>
+
+</Tabs>
+
+## Unload a snapshot
+
+<Tabs>
+<Tab heading="Web UI" group="ui">
+    <Tip title="Permissions Required">
+        This requires snapshot management permissions.
+    </Tip>
+
+1. Navigate to the details view
+    ![Snapshot details link emphasized](/img/ui-secret-recovery-details-link.png)
+2. Unload the snapshot via the action menu
+    ![Snapshot unload action emphasized](/img/ui-secret-recovery-unload.png)
+
+</Tab>
+<Tab heading="API call using cURL" group="api">
+
+```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
+
+```
+</Tab>
+</Tabs>

content/vault/v1.21.x (rc)/data/docs-nav-data.json

@@ -203,6 +203,15 @@
           }
         ]
       },
+      {
+        "title": "Data Recovery",
+          "path": "concepts/data-recovery",
+          "badge": {
+            "text": "ENT",
+            "type": "filled",
+            "color": "neutral"
+        }
+      },
       {
         "title": "Transform",
         "path": "concepts/transform"