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

Open
wants to merge 14 commits into
base: main
Choose a base branch
from

Conversation

hellobontempo
Copy link
Contributor

@hellobontempo hellobontempo commented Dec 2, 2024

Description

Preview here.

  • Replace screenshot to display the overview card (the original screenshot showed the secret data page, but this data is actually returned from the READ :engine/data/:secret_path endpoint and not the /subkeys one)
  • Add enterprise banner, viewing subkeys is an enterprise only feature.
  • Add screenshot with the Reveal subkeys toggled on which is the second place in the GUI where subkeys are viewable

TODO only if you're a HashiCorp employee

  • Backport Labels: If this fix needs to be backported, use the appropriate backport/ label that matches the desired release branch. Note that in the CE repo, the latest release branch will look like backport/x.x.x, but older release branches will be backport/ent/x.x.x+ent.
    • LTS: If this fixes a critical security vulnerability or severity 1 bug, it will also need to be backported to the current LTS versions of Vault. To ensure this, use all available enterprise labels.
  • ENT Breakage: If this PR either 1) removes a public function OR 2) changes the signature
    of a public function, even if that change is in a CE file, double check that
    applying the patch for this PR to the ENT repo and running tests doesn't
    break any tests. Sometimes ENT only tests rely on public functions in CE
    files.
  • Jira: If this change has an associated Jira, it's referenced either
    in the PR description, commit message, or branch name.
  • RFC: If this change has an associated RFC, please link it in the description.
  • ENT PR: If this change has an associated ENT PR, please link it in the
    description. Also, make sure the changelog is in this PR, not in your ENT PR.

@github-actions github-actions bot added the hashicorp-contributed-pr If the PR is HashiCorp (i.e. not-community) contributed label Dec 2, 2024
Copy link

github-actions bot commented Dec 2, 2024

Build Results:
All builds succeeded! ✅

Copy link

github-actions bot commented Dec 2, 2024

CI Results:
All Go tests succeeded! ✅

@@ -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 😄

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

@hellobontempo hellobontempo Dec 2, 2024

Choose a reason for hiding this comment

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

Now that the kv engine includes an "overview" page, some actions require navigating to the "Secrets" tab while others can be done from the overview. I updated the various sub-steps to include or not include this step accordingly, but let me know if this should be reverted!

@schavis schavis self-requested a review December 3, 2024 21:46
schavis
schavis previously approved these changes Dec 3, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
backport/1.18.x hashicorp-contributed-pr If the PR is HashiCorp (i.e. not-community) contributed pr/no-changelog pr/no-milestone
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants