Skip to content

Snapshot Single Item Recovery Docs #1096

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Oct 21, 2025
Merged

Snapshot Single Item Recovery Docs #1096

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
40cae9e
add snapshot item recovery docs
lane-wetmore Oct 10, 2025
ae5a263
update description
lane-wetmore Oct 10, 2025
cab15a0
fix indentation
lane-wetmore Oct 13, 2025
a210335
update desc
lane-wetmore Oct 13, 2025
4931381
Merge branch 'main' into lane-wetmore/single-item-recovery
lane-wetmore Oct 17, 2025
47a8bfa
move new docs into previous doc pages
lane-wetmore Oct 17, 2025
de0854d
remove unused screenshots
lane-wetmore Oct 17, 2025
cfcb6e1
move content to partial and active voice rewrites
lane-wetmore Oct 20, 2025
3db6479
remove extra screenshots
lane-wetmore Oct 20, 2025
dca1f71
Merge branch 'main' into lane-wetmore/single-item-recovery
schavis Oct 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions ....x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,37 @@ Load the snapshot holding the secret you want to recover:

<Tabs>

<Tab heading="Web UI" group="ui">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<Tab heading="Web UI" group="ui">
<Tab heading="GUI" group="gui">

The established tab name/group for GUI instructions is "GUI"


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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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>
Snapshot load and unload operations are restricted to the root namespace. All other snapshot operations
can be performed in other namespaces.
1. Open the Vault GUI and sign in to the root namespace. While you can perform
other snapshot operations from any namespace, you must perform load and
unload operations under the `root` namespace.

Style correction: write in active voice
Structural correction: whenever possible, include information in normal text rather than asides

Since the permission requirement is a prerequisite, we should add it to the "Before you start" section, especially since it's probably not just a GUI requirement


2. Select **Secrets Recovery** from the left navigation menu.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. Select **Secrets Recovery** from the left navigation menu.
1. Select **Secrets Recovery** from the navigation menu.

Markdown correction: use 1. for all items in a numbered list
Style correction: avoid referencing specific positions on the screen for UI elements


3. Select **Upload snapshot**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
3. Select **Upload snapshot**.
1. Select **Upload snapshot**.

![Load snapshot button location emphasized](/img/ui-secret-recovery-upload.png)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We really try to avoid multiple screenshots because of the maintenance cost. Is there a single, "hero" screenshot we can provide that we can use to make sure folks know they're on the right screen?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could remove the screenshot of the upload form. If we can only have one screenshot, I'd rather keep the screenshot which shows a loaded snapshot view rather than the empty state screenshot.


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
to learn more about automated snapshots.
1. Select your upload method. To use an automted snapshot you must provide an
[automated snapshot config](/vault/api-docs/system/storage/raftautosnapshots#load-a-snapshot-from-an-automated-snapshot-configuration).

Style correction: write in active voice

![Load snapshot form](/img/ui-secret-recovery-upload-form.png)

5. Click **Load snapshot** to complete the upload.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
5. Click **Load snapshot** to complete the upload.
1. Click **Load snapshot** to complete the upload.

6. The status of the snapshot and the expiration date is shown. This also allows
navigation to the snapshot details view.
![Snapshot overview card with status and details link emphasized](/img/ui-secret-recovery-overview-details.png)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
6. The status of the snapshot and the expiration date is shown. This also allows
navigation to the snapshot details view.
![Snapshot overview card with status and details link emphasized](/img/ui-secret-recovery-overview-details.png)
1. Monitor the upload until the status says "Ready" and the expiration date
populates.
1. Click "View details &rarr; to open the snapshot details view.


</Tab>

<Tab heading="CLI" group="cli">

<Tabs>
Expand Down Expand Up @@ -104,6 +135,15 @@ You can check for a loaded snapshot by listing the loaded snapshots:

<Tabs>

<Tab heading="Web UI" group="ui">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<Tab heading="Web UI" group="ui">
<Tab heading="GUI" group="gui">


1. Select **Secrets Recovery** from the left navigation menu.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Select **Secrets Recovery** from the left navigation menu.
![Loaded snapshot card emphasized](/img/ui-secret-recovery-loaded-snapshot.png)
Select **Secrets Recovery** from the navigation menu. to view currently loaded snapshots.


2. If a snapshot has been loaded, it will appear here.
![Loaded snapshot card emphasized](/img/ui-secret-recovery-loaded-snapshot.png)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. If a snapshot has been loaded, it will appear here.
![Loaded snapshot card emphasized](/img/ui-secret-recovery-loaded-snapshot.png)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is really just a single step (selecting the menu entry, so we can combine them


</Tab>

<Tab heading="CLI" group="cli">

@include 'sysadmin/snapshots/list-snapshots/cli.mdx'
Expand All @@ -130,6 +170,23 @@ storage.

<Tabs>

<Tab heading="Web UI" group="ui">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<Tab heading="Web UI" group="ui">
<Tab heading="GUI" group="gui">

<Tip title="Permissions Required">
This requires read and/or recover permissions specific to the resource.
</Tip>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<Tip title="Permissions Required">
This requires read and/or recover permissions specific to the resource.
</Tip>

We should add the permission requirements to "Before you start"


1. A namespace selector will show when in the root namespace. Fill in the available fields to locate the secret to read or recover.
![Snapshot read and recover form fields](/img/ui-secret-recovery-fields.png)

2. 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)

3. 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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. A namespace selector will show when in the root namespace. Fill in the available fields to locate the secret to read or recover.
![Snapshot read and recover form fields](/img/ui-secret-recovery-fields.png)
2. 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)
3. 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)
![Snapshot read and recover form fields](/img/ui-secret-recovery-fields.png)
Use the namespace selector to find the secret you want to read or recover. Once
you recover the snapshot, you can:
- view the snapshot data as key/value pairs or as a JSON object.
- recover the original resource path
- recover the original resource to a new path

Again, this is just a single step so a numbered list doesn't really make sense


</Tab>

<Tab heading="CLI" group="cli">

@include 'sysadmin/snapshots/secret-restore/recover/cli.mdx'
Expand All @@ -150,6 +207,16 @@ storage.

<Tabs>

<Tab heading="Web UI" group="ui">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<Tab heading="Web UI" group="ui">
<Tab heading="Web GUI" group="gui">

<Tip title="Permissions Required">
This requires recover permissions specific to the resource.
</Tip>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<Tip title="Permissions Required">
This requires recover permissions specific to the resource.
</Tip>

Move permission requirements to "Before you start"


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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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)
If the recovery operation succeeds, the GUI displays a success message with a
link to the recovered resource.
![Snapshot recovery operation](/img/ui-secret-recovery-recover-message.png)

Style correction: write in active voice


</Tab>

<Tab heading="CLI" group="cli">

@include 'sysadmin/snapshots/secret-restore/verify/cli.mdx'
Expand Down
67 changes: 67 additions & 0 deletions ...1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/single-cluster.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,37 @@ Load the snapshot holding the secret you want to recover.

<Tabs>

<Tab heading="Web UI" group="ui">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<Tab heading="Web UI" group="ui">
<Tab heading="GUI" group="gui">

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like all the steps on this pages are the same as the replicated cluster instructions? If so, we should move them into partials (like the CLI and API directions) so we can use them across both pages


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.
6. The status of the snapshot and the expiration date is shown. This also allows
navigation to the snapshot details view.
![Snapshot overview card with status and details link emphasized](/img/ui-secret-recovery-overview-details.png)

</Tab>

<Tab heading="CLI" group="cli">

<Tabs>
Expand Down Expand Up @@ -99,6 +130,15 @@ updating the loaded snapshot as new automated snapshots are created.
You can check for a loaded snapshot by listing the loaded snapshots:

<Tabs>

<Tab heading="Web UI" group="ui">

1. Select **Secrets Recovery** from the left navigation menu.

2. If a snapshot has been loaded, it will appear here.
![Loaded snapshot card emphasized](/img/ui-secret-recovery-loaded-snapshot.png)

</Tab>

<Tab heading="CLI" group="cli">

Expand Down Expand Up @@ -126,6 +166,23 @@ storage.

<Tabs>

<Tab heading="Web UI" group="ui">
<Tip title="Permissions Required">
This requires read and/or recover permissions specific to the resource.
</Tip>

1. A namespace selector will show when in the root namespace. Fill in the available fields to locate the secret to read or recover.
![Snapshot read and recover form fields](/img/ui-secret-recovery-fields.png)

2. 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)

3. 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="CLI" group="cli">

@include 'sysadmin/snapshots/secret-restore/recover/cli.mdx'
Expand All @@ -146,6 +203,16 @@ storage.

<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)

</Tab>

<Tab heading="CLI" group="cli">

@include 'sysadmin/snapshots/secret-restore/verify/cli.mdx'
Expand Down
Binary file added content/vault/v1.21.x (rc)/img/ui-secret-recovery-fields.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/vault/v1.21.x (rc)/img/ui-secret-recovery-loaded-snapshot.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/vault/v1.21.x (rc)/img/ui-secret-recovery-overview-details.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/vault/v1.21.x (rc)/img/ui-secret-recovery-read-json.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/vault/v1.21.x (rc)/img/ui-secret-recovery-read-kv.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/vault/v1.21.x (rc)/img/ui-secret-recovery-recover-copy.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/vault/v1.21.x (rc)/img/ui-secret-recovery-recover-message.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/vault/v1.21.x (rc)/img/ui-secret-recovery-upload-form.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/vault/v1.21.x (rc)/img/ui-secret-recovery-upload.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading