diff --git a/content/vault/v1.21.x (rc)/content/docs/concepts/data-recovery/index.mdx b/content/vault/v1.21.x (rc)/content/docs/concepts/data-recovery/index.mdx new file mode 100644 index 0000000000..b36ac73a8b --- /dev/null +++ b/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. + + + + + +1. Open a web browser to access the Vault UI and sign in to the root namespace. + + + Snapshot load and unload operations are restricted to the root namespace. All other snapshot operations + can be performed in other namespaces. + + + + + This requires snapshot management permissions. + + +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. + + + + + +@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 +``` + + + + + +## 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 + + + + + This requires recover permissions specific to the resource. + + +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) + + + +```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 +``` + + + + +## Snapshot read + + + + + This requires read permissions specific to the resource. + + +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) + + + + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load/2403d301-94f2-46a1-a39d-02be83e2831a + +``` + + + + + +## Unload a snapshot + + + + + This requires snapshot management permissions. + + +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) + + + + +```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 + +``` + + diff --git a/content/vault/v1.21.x (rc)/data/docs-nav-data.json b/content/vault/v1.21.x (rc)/data/docs-nav-data.json index af5df94c8b..3bd0a768b7 100644 --- a/content/vault/v1.21.x (rc)/data/docs-nav-data.json +++ b/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" diff --git a/content/vault/v1.21.x (rc)/img/ui-secret-recovery-details-link.png b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-details-link.png new file mode 100644 index 0000000000..792ad5fe4e Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-details-link.png differ diff --git a/content/vault/v1.21.x (rc)/img/ui-secret-recovery-overview-details.png b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-overview-details.png new file mode 100644 index 0000000000..6622e07f84 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-overview-details.png differ diff --git a/content/vault/v1.21.x (rc)/img/ui-secret-recovery-read-json.png b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-read-json.png new file mode 100644 index 0000000000..045fd6b4e6 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-read-json.png differ diff --git a/content/vault/v1.21.x (rc)/img/ui-secret-recovery-read-kv.png b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-read-kv.png new file mode 100644 index 0000000000..b9668e6b0f Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-read-kv.png differ diff --git a/content/vault/v1.21.x (rc)/img/ui-secret-recovery-recover-copy.png b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-recover-copy.png new file mode 100644 index 0000000000..c5da8818c3 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-recover-copy.png differ diff --git a/content/vault/v1.21.x (rc)/img/ui-secret-recovery-recover-message.png b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-recover-message.png new file mode 100644 index 0000000000..4be2e9c049 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-recover-message.png differ diff --git a/content/vault/v1.21.x (rc)/img/ui-secret-recovery-unload.png b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-unload.png new file mode 100644 index 0000000000..860ae4b904 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-unload.png differ diff --git a/content/vault/v1.21.x (rc)/img/ui-secret-recovery-upload-form.png b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-upload-form.png new file mode 100644 index 0000000000..72347c2f22 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-upload-form.png differ diff --git a/content/vault/v1.21.x (rc)/img/ui-secret-recovery-upload.png b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-upload.png new file mode 100644 index 0000000000..4a17fa62b0 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/ui-secret-recovery-upload.png differ