diff --git a/changelog/30739.txt b/changelog/30739.txt new file mode 100644 index 0000000000..d20b759ac7 --- /dev/null +++ b/changelog/30739.txt @@ -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. +``` diff --git a/website/content/api-docs/secret/cubbyhole.mdx b/website/content/api-docs/secret/cubbyhole.mdx index e819969950..3fc4b71717 100644 --- a/website/content/api-docs/secret/cubbyhole.mdx +++ b/website/content/api-docs/secret/cubbyhole.mdx @@ -27,8 +27,10 @@ This endpoint retrieves the secret at the specified location. - `path` `(string: )` – Specifies the path of the secret to read. This is specified as part of the URL. +- `read_snapshot_id` `(string: )` - 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: )` – Specifies the path of the secrets to list. This is specified as part of the URL. +- `read_snapshot_id` `(string: )` - 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: )` – The target path of the secrets you want to recover. +- `recover_snapshot_id` `(string: )` - 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. diff --git a/website/content/api-docs/secret/kv/kv-v1.mdx b/website/content/api-docs/secret/kv/kv-v1.mdx index 029d5fa349..b4ae3df80c 100644 --- a/website/content/api-docs/secret/kv/kv-v1.mdx +++ b/website/content/api-docs/secret/kv/kv-v1.mdx @@ -28,8 +28,9 @@ This endpoint retrieves the secret at the specified location. - `path` `(string: )` – Specifies the path of the secret to read. This is specified as part of the URL. +- `recover_snapshot_id` `(string: )` - 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: )` – Specifies the path of the secrets to list. This is specified as part of the URL. +- `recover_snapshot_id` `(string: )` - 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: )` – The target path of the secrets you want to recover. +- `recover_snapshot_id` `(string: )` - 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. diff --git a/website/content/api-docs/system/storage/raftautosnapshots.mdx b/website/content/api-docs/system/storage/raftautosnapshots.mdx index 38d7fec215..66685e356c 100644 --- a/website/content/api-docs/system/storage/raftautosnapshots.mdx +++ b/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: )` - 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' + + + + 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. + + + +| Method | Path | +| :----- | :---------------------------------------------------- | +| `POST` | `/sys/storage/raft/snapshot-auto/snapshot-load/:name` | + + +### Parameters + +- `name` `(string: )` – Name of the configuration that created the snapshot. + +- `url` `(string: )` - 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" + } +} +``` + diff --git a/website/content/api-docs/system/storage/raftsnapshotload.mdx b/website/content/api-docs/system/storage/raftsnapshotload.mdx new file mode 100644 index 0000000000..55c021e8d1 --- /dev/null +++ b/website/content/api-docs/system/storage/raftsnapshotload.mdx @@ -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 +``` diff --git a/website/content/docs/commands/list.mdx b/website/content/docs/commands/list.mdx index 9caed719a0..2536239f79 100644 --- a/website/content/docs/commands/list.mdx +++ b/website/content/docs/commands/list.mdx @@ -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. diff --git a/website/content/docs/commands/operator/raft.mdx b/website/content/docs/commands/operator/raft.mdx index 59fa0ead31..a2292aa210 100644 --- a/website/content/docs/commands/operator/raft.mdx +++ b/website/content/docs/commands/operator/raft.mdx @@ -158,34 +158,77 @@ Usage: vault operator raft remove-peer ## 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 [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 - - 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 ``` -~> **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 $ 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 +Usage: vault operator raft snapshot save + + 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 + + Unloads the snapshot with the provided ID. + + $ vault operator raft snapshot unload 8a4f31cc-7bb2-227a-aa18-8f140fb40f10 ``` ## autopilot diff --git a/website/content/docs/commands/read.mdx b/website/content/docs/commands/read.mdx index 9cc1d402dc..aaafa3eec8 100644 --- a/website/content/docs/commands/read.mdx +++ b/website/content/docs/commands/read.mdx @@ -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 diff --git a/website/content/docs/commands/recover.mdx b/website/content/docs/commands/recover.mdx new file mode 100644 index 0000000000..9a53820443 --- /dev/null +++ b/website/content/docs/commands/recover.mdx @@ -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. diff --git a/website/content/docs/concepts/integrated-storage/snapshot-recover.mdx b/website/content/docs/concepts/integrated-storage/snapshot-recover.mdx new file mode 100644 index 0000000000..cc6c1dc5d8 --- /dev/null +++ b/website/content/docs/concepts/integrated-storage/snapshot-recover.mdx @@ -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 secret/my-secret +``` + +To list the secrets at a specific path from the snapshot: +```shell +$ vault list -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 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"] +} +``` diff --git a/website/content/docs/concepts/policies.mdx b/website/content/docs/concepts/policies.mdx index 4226fa9160..a3772b4569 100644 --- a/website/content/docs/concepts/policies.mdx +++ b/website/content/docs/concepts/policies.mdx @@ -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 diff --git a/website/content/partials/recover/deletedmounts.mdx b/website/content/partials/recover/deletedmounts.mdx new file mode 100644 index 0000000000..22505b1458 --- /dev/null +++ b/website/content/partials/recover/deletedmounts.mdx @@ -0,0 +1,10 @@ + + + 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. + + + diff --git a/website/content/partials/recover/loadedsnapshots.mdx b/website/content/partials/recover/loadedsnapshots.mdx new file mode 100644 index 0000000000..ab6a528d48 --- /dev/null +++ b/website/content/partials/recover/loadedsnapshots.mdx @@ -0,0 +1,13 @@ + + + * 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. + + diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 382a09d5a5..5fa3b51fcc 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -764,6 +764,10 @@ { "title": "/sys/storage/raft/snapshot-auto", "path": "system/storage/raftautosnapshots" + }, + { + "title": "/sys/storage/raft/snapshot-load", + "path": "system/storage/raftsnapshotload" } ] }, diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index b3ea945521..da2fc2e759 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -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": "read", "path": "commands/read" }, + { + "title": "recover", + "path": "commands/recover" + }, { "title": "secrets", "routes": [