diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx index 66685e356c..dd168f98a6 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx @@ -58,6 +58,20 @@ environment variables or files on disk in predefined locations. or "google-gcs". The remaining parameters described below are all specific to the selected `storage_type` and prefixed accordingly. +- `autoload_enabled` `(bool: false)` - Have Vault automatically load the latest snapshot + after it is written. This will replace the previously loaded snapshot. + Note that this does not mean the snapshot is automatically applied to the + cluster, it is just loaded and available for recovery operations. Not allowed + for `storage_type=local`. Can only be enabled for one configuration at a time. + + + +If you set `autoload_enabled=true` for a configuration and that configuration's +`interval` is less than 1 hour, Vault will only load a new snapshot at most once +per hour. + + + #### storage_type=local - `local_max_space` `(integer: )` - For `storage_type=local`, the maximum @@ -284,6 +298,43 @@ $ curl \ } ``` +### Sample response with autoloading enabled + +```json +{ + "data": { + "last_snapshot_end": "2025-08-29T17:41:55+02:00", + "last_snapshot_error": "", + "last_snapshot_start": "2025-08-29T17:41:54+02:00", + "last_snapshot_url": "https://example.com/snapshots/vault-snapshot-1603898241699731000.snap", + "loaded_snapshot_expires_at": "2025-09-01T17:41:55+02:00", + "loaded_snapshot_id": "42596c4c-6f4b-c476-8eb0-90546cdda7f3", + "loaded_snapshot_status": "ready", + "next_snapshot_start": "2025-08-29T17:46:55+02:00", + "snapshot_start": "2025-08-29T17:41:55+02:00", + "snapshot_url": "https://example.com/snapshots/vault-snapshot-1603898241699731000.snap" + } +} +``` + +### Sample response with an autoloading failure + +```json +{ + "data": { + "last_snapshot_end": "2025-08-29T17:41:55+02:00", + "last_snapshot_error": "", + "last_snapshot_start": "2025-08-29T17:41:54+02:00", + "last_snapshot_url": "https://example.com/snapshots/vault-snapshot-1603898241699731000.snap", + "loading_error": "error loading snapshot: a snapshot is loaded already", + "next_snapshot_start": "2025-08-29T17:46:55+02:00", + "snapshot_start": "2025-08-29T17:41:55+02:00", + "snapshot_url": "https://example.com/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 diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftsnapshotload.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftsnapshotload.mdx index 55c021e8d1..ca976701ff 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftsnapshotload.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftsnapshotload.mdx @@ -43,6 +43,7 @@ $ curl \ { "data": { "cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8", + "created_at": "2025-05-22T15:07:58.187769+01:00", "expires_at": "2025-05-25T15:07:58.187769+01:00", "snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a", "status": "loading" @@ -101,6 +102,7 @@ For a snapshot loaded as a binary file: { "data": { "cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8", + "created_at": "2025-05-22T15:07:58.187769+01:00", "expires_at": "2025-05-25T15:07:58.187769+01:00", "snapshot_id": "2403d301-94f2-46a1-a39d-02be83e2831a", "status": "ready" @@ -108,17 +110,18 @@ For a snapshot loaded as a binary file: } ``` -For a snapshot loaded from a an Automated Snapshot configuration: +For a snapshot loaded from an Automated Snapshot configuration: ```json { "data": { "auto_config_name": "config1", "cluster_id": "2ec84695-cfe5-44f3-b351-3f08a9ccc0c8", + "created_at": "2025-05-22T15:07:58.187769+01:00", "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" + "status": "ready", + "url": "https://example.com/raft.snap" } } ``` @@ -131,6 +134,11 @@ Unloads a currently loaded snapshot from the cluster. | :------- | :--------------------------------------------- | | `DELETE` | `/sys/storage/raft/snapshot-load/:snapshot_id` | +### Query parameters + +- `force` (boolean: false) - If set to `true`, forces the unload of a snapshot + even if it is in use by an ongoing recovery operation or is still loading. + ### Sample request ```shell-session @@ -138,4 +146,4 @@ $ curl \ --header "X-Vault-Token: ..." \ --request DELETE \ http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-load/2403d301-94f2-46a1-a39d-02be83e2831a -``` +``` \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx index 3fc3b56c0a..1cdfbd1fc1 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx @@ -173,3 +173,102 @@ $ curl \ + +## Step 3 (Optional): Enable autoloading + +You can configure Vault to automatically load the latest snapshot after +it is written. This is useful if you want to quickly be able to [recover individual +secrets](/vault/docs/sysadmin/recover-a-secret) from a snapshot without having to +manually load the snapshot. + +Only one automated snapshot configuration can have autoloading enabled at a time. +Automated snapshot configurations with their storage type set to `local` cannot +have autoloading enabled. + +If the interval for the automated snapshot configuration is set to less than 1 hour, +Vault will only autoload snapshots every hour. This is to prevent excessive load on the cluster. + +To enable autoloading, set the `autoload_enabled` parameter to `true` when creating or updating +the automated snapshot configuration. For example, we can update the previous AWS S3 example to enable +autoloading: + +```json +{ + "storage_type": "aws-s3", + "file_prefix": "paris", + "interval": "8h", + "retain": 30, + "autoload_enabled": true, + "local_max_space": 2621440000, + "path_prefix": "primary", + "aws_s3_bucket": "vault-snapshots", + "aws_s3_region": "eu-west-3", + "aws_access_key_id": "ASI...COFFEE", + "aws_secret_access_key": "wJalr...COFFEEKEY", + "aws_session_token": "IQoJb3JpZ2luX2IQ...COFFEE", + "aws_s3_server_side_encryption": "true" +} +``` + +and update the configuration in our Vault cluster: + + + + + +Run `vault write` with the +[`/sys/storage/raft/snapshot-auto`](/vault/api-docs/system/storage/raftautosnapshots#create-update-an-automated-snapshots-config) +path and your snapshot configuration to update an automated snapshot configuration: + +```shell-session +$ vault write \ + sys/storage/raft/snapshot-auto/config/ \ + @ +``` + +To update the previous AWS S3 example to enable autoloading: + + +```shell-session +$ vault write \ + sys/storage/raft/snapshot-auto/config/paris-primary \ + @aws-snapshot.json +``` + + + + + + + +Call the +[`/sys/storage/raft/snapshot-auto`](/vault/api-docs/system/storage/raftautosnapshots#create-update-an-automated-snapshots-config) +endpoint with your configuration file to update an automated snapshot configuration: + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @ \ + ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-auto/config/ +``` + + +To update the previous AWS S3 example to enable autoloading: + + + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + --data @aws-snapshot.json \ + ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-auto/config/paris-primary +``` + + + + + + + diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx index dcaf86784b..a30b5a9e37 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx @@ -94,7 +94,29 @@ Status key | Description `ready` | Loading completed successfully. You can read data from the snapshot. `error` | Loading failed. Refer to the logs and error details for troubleshooting. +### Use an autoloaded snapshot +If you configured automated snapshots with [autoloading enabled](/vault/docs/sysadmin/snapshots/automate#step-3-optional-enable-autoloading), +Vault Enterprise will automatically load a snapshot when the cluster starts and keep +updating the loaded snapshot as new automated snapshots are created. + +You can check for a loaded snapshot by listing the loaded snapshots: + + + + + +@include 'sysadmin/snapshots/list-snapshots/cli.mdx' + + + + + +@include 'sysadmin/snapshots/list-snapshots/api.mdx' + + + + ## Step 2: Recover the secret diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/single-cluster.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/single-cluster.mdx index e4d9735093..e33aa81a21 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/single-cluster.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/single-cluster.mdx @@ -90,8 +90,29 @@ Status key | Description `error` | Loading failed. Refer to the logs and `error` field for details. +### Use an autoloaded snapshot +If you configured automated snapshots with [autoloading enabled](/vault/docs/sysadmin/snapshots/automate#step-3-optional-enable-autoloading), +Vault Enterprise will automatically load a snapshot when the cluster starts and keep +updating the loaded snapshot as new automated snapshots are created. +You can check for a loaded snapshot by listing the loaded snapshots: + + + + + +@include 'sysadmin/snapshots/list-snapshots/cli.mdx' + + + + + +@include 'sysadmin/snapshots/list-snapshots/api.mdx' + + + + ## Step 2: Recover the secret diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/list-snapshots/api.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/list-snapshots/api.mdx new file mode 100644 index 0000000000..5090507f08 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/list-snapshots/api.mdx @@ -0,0 +1,30 @@ +You can check to see if there is a snapshot currently loaded by querying +the `/sys/storage/raft/snapshot-load` endpoint: + +```shell-session +$ curl \ + --request LIST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load +``` + +For example: + + + +```shell-session +$ curl \ + --request LIST \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load + +{ + "data": { + "keys": [ + "9465df92-8236-4af9-8cc8-b7460d882e41" + ] + } +} +``` + + diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/list-snapshots/cli.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/list-snapshots/cli.mdx new file mode 100644 index 0000000000..ca5ccd2033 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/list-snapshots/cli.mdx @@ -0,0 +1,20 @@ +You can check to see if there is a snapshot currently loaded by using `vault list` +and the `/sys/storage/raft/snapshot-load` endpoint: + +```shell-session +$ vault list /sys/storage/raft/snapshot-load +``` + +For example: + + + +```shell-session +$ vault list /sys/storage/raft/snapshot-load + +Keys +---- +9465df92-8236-4af9-8cc8-b7460d882e41 +``` + + \ No newline at end of file