Skip to content
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.

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

Docs: Add updated screenshots to kv subkey docs #29067

Merged
merged 14 commits into from
Dec 4, 2024
15 changes: 11 additions & 4 deletions website/content/docs/secrets/kv/kv-v2/cookbook/read-subkey.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ Read the available subkeys on an existing data path in the `kv` v2 plugin.

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

Use `vault read` with the `/subkeys` metadata path retrieve a list of available
schavis marked this conversation as resolved.
Show resolved Hide resolved
subkeys on the given path.
Use `vault read` with the `/subkeys` path to retrieve a list of secret data
subkeys at the given path.

```shell-session
$ vault read <mount_path>/subkeys/<secret_path>
Expand Down Expand Up @@ -50,12 +50,19 @@ subkeys map[prod:<nil> sandbox:<nil> smoke:<nil>]

<Tab heading="GUI" group="gui">

@include 'alerts/enterprise-only.mdx'

@include 'gui-page-instructions/select-kv-mount.mdx'

- Click through the path segments to select the relevant secret path.
- Note the subkeys listed on the data page.
- Note the subkeys card on the overview page.

![Partial screenshot of the Vault GUI showing two key/value pairs at the path dev/square-api. The "prod" key is visible](/img/gui/kv/overview-page.png)

- Click **Patch latest version +** on the key/value page.
- Toggle **Reveal subkeys in JSON**

![Partial screenshot of the Vault GUI showing two key/value pairs at the path dev/square-api. The "prod" key is visible](/img/gui/kv/read-data.png)
![Partial screenshot of the Vault GUI showing the patch form with "reveal subkeys" toggled on. The "prod" key is visible](/img/gui/kv/patch-reveal-subkeys.png)

</Tab>

Expand Down
1 change: 1 addition & 0 deletions website/content/docs/secrets/kv/kv-v2/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ Basic examples:
- [Set max data versions](/vault/docs/secrets/kv/kv-v2/cookbook/max-versions)
- [Write data](/vault/docs/secrets/kv/kv-v2/cookbook/write-data)
- [Patch and update data](/vault/docs/secrets/kv/kv-v2/cookbook/patch-data)
- [Read subkeys](/vault/docs/secrets/kv/kv-v2/cookbook/read-subkey)
- [Soft delete data](/vault/docs/secrets/kv/kv-v2/cookbook/delete-data)
- [Restore soft deleted data](/vault/docs/secrets/kv/kv-v2/cookbook/undelete-data)
- [Destroy data](/vault/docs/secrets/kv/kv-v2/cookbook/destroy-data)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
- Open the data page for your `kv` plugin:
- Navigate to your `kv` plugin:

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Feel free to revert, but I removed "data" here because "metadata" and "data" are key words in kv v2 and get confused a lot. In this engine it seems helpful to remove data unless we're talking specifically about "secret data" or endpoints that include /data/.

Copy link
Contributor

Choose a reason for hiding this comment

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

Can you elaborate on the source of the confusion? They may be keywords, but "data" is also an English word that accurately describes the stuff stored in the kv plugin. I'm not against changing things to clarify, but avoiding the word altogether doesn't feel like a reasonable long-term solution.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Sure! I don't mean we should remove the use of data all together, but I think in regards to kv v2 specifically we should be intentional how we use it. Since kv v2 plugins store "secret data" and "metadata," using "data" to encompass both can be confusing.

Most of the time this distinction will probably just be important internally. However, in this context it sounds like users are navigating to secret data, which is not true (anymore). Now the overview page exists as a intermediary layer and clicking a secret path from the list no longer directs users to the "data page."

The overview was added as an additional layer of security so users with read capabilities to :engine/data/:secret_path wouldn't inadvertently read sensitive secret values when clicking into a secret path. So while the overview technically contains data about the secret, the "data" distinction is important here so we're clear it's not secret data.

Happy to discuss over zoom if that's easier 😄

1. Open the GUI for your Vault instance.

Expand All @@ -9,6 +9,4 @@

1. Select the mount path for your `kv` plugin.

1. Click through the path segments to select the relevant secret path.

1. Select the **Secret** tab
1. Click through the path segments to select the relevant secret path.
Binary file added website/public/img/gui/kv/overview-page.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading