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

Use new -mount syntax for all KV subcommands in 1.11 docs #16002

Merged
merged 4 commits into from
Jun 15, 2022

Conversation

digivava
Copy link
Collaborator

I have updated all docs pages dealing with the KV CLI to use the new -mount flag syntax, which was created to mitigate confusion caused by the previous syntax for interacting with KV secrets in the CLI.

These docs pages will now match the text produced by calling a vault kv subcommand with the -help flag.

Background

This syntax is optional, allowing users to do vault kv get -mount=secret foo instead of the old vault kv get secret/foo. While the old way may look prettier, it turned out this syntax caused a lot of confusion for new users, who quickly run into issues caused by the fact that secret/foo looks like a path but is not actually the real path to the secret for KV v2 (secret/data/foo). The real path is used by policies and the API, so users fresh off the Getting Started guide often don't understand why their policies or CLI commands don't work when they try to use the same "path" for both.

Caveats

I continued to use the old syntax on the index page for CLI commands in general, since that page is aimed at showcasing concepts that are true across all Vault CLI commands. This mount flag syntax only works for the kv subcommands, so I didn't want to muddy the message of that page. So, on that page I call out the existence of this flag in a KV-specific paragraph down below, but otherwise leave those examples alone.

@digivava digivava added this to the 1.11.0 milestone Jun 15, 2022
@digivava digivava requested a review from a team June 15, 2022 20:55
Copy link
Contributor

@taoism4504 taoism4504 left a comment

Choose a reason for hiding this comment

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

minor nits, but otherwise LGTM

digivava added a commit that referenced this pull request Jun 15, 2022
* Use new -mount syntax for all KV subcommands in 1.11 docs

* Use more appropriate heading size for mount flag syntax

* Add the explanatory syntax blurb from the -help text

* Adjust some wording
digivava added a commit that referenced this pull request Jun 15, 2022
…16004)

* Use new -mount syntax for all KV subcommands in 1.11 docs

* Use more appropriate heading size for mount flag syntax

* Add the explanatory syntax blurb from the -help text

* Adjust some wording
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants