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

…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

website/content/docs/commands/index.mdx

@@ -206,6 +206,13 @@ Note that if an argument is supplied in a @key=value format, Vault will treat th
 kv pair with the key being `@key`, not a file called `key=value`. This also means that Vault
 does not support filenames with `=` in them.
 
+## Mount flag syntax (KV)
+
+All `kv` commands can alternatively refer to the path to the KV secrets engine using a flag-based syntax like `$ vault kv get -mount=secret password` 
+instead of `$ vault kv get secret/password`. The mount flag syntax was created to mitigate confusion caused by the fact that for KV v2 secrets, 
+their full path (used in policies and raw API calls) actually contains a nested `/data/` element (e.g. `secret/data/password`) which can be easily overlooked when using 
+the above KV v1-like syntax `secret/password`. To avoid this confusion, all KV-specific docs pages will use the `-mount` flag.
+
 ## Exit Codes
 
 The Vault CLI aims to be consistent and well-behaved unless documented

website/content/docs/commands/kv/delete.mdx

@@ -19,15 +19,15 @@ normal get requests.
 Delete the latest version of the key "creds":
 
 ```shell-session
-$ vault kv delete secret/creds
+$ vault kv delete -mount=secret creds
 Success! Data deleted (if it existed) at: secret/creds
 ```
 
 **[K/V Version 2]** Delete version 11 of key "creds":
 
 ```shell-session
-$ vault kv delete -versions=11 secret/creds
-Success! Data deleted (if it existed) at: secret/creds
+$ vault kv delete -mount=secret -versions=11 creds
+Success! Data deleted (if it existed) at: secret/data/creds
 ```
 
 ## Usage
@@ -37,8 +37,14 @@ included on all commands.
 
 ### Command Options
 
+- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted. 
+  If specified, the next argument will be interpreted as the secret path. If 
+  this flag is not specified, the next argument will be interpreted as the 
+  combined mount path and secret path, with /data/ automatically inserted for 
+  KV v2 secrets.
+
 - `-versions` `([]int: <required>)` - The versions to be deleted. The versioned
   data will not be deleted, but it will no longer be returned in normal get
   requests.
 
-~> **NOTE:** This command option is only for K/V v2.
+~> **NOTE:** The `-versions` command option is only for K/V v2.

website/content/docs/commands/kv/destroy.mdx

@@ -20,7 +20,7 @@ taken.
 Destroy version 11 of the key "creds":
 
 ```shell-session
-$ vault kv destroy -versions=11 secret/creds
+$ vault kv destroy -mount=secret -versions=11 creds
 Success! Data written to: secret/destroy/creds
 ```
 
@@ -37,5 +37,11 @@ included on all commands.
 
 ### Command Options
 
+- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted. 
+  If specified, the next argument will be interpreted as the secret path. If 
+  this flag is not specified, the next argument will be interpreted as the 
+  combined mount path and secret path, with /data/ automatically inserted for 
+  KV v2 secrets.
+
 - `-versions` `([]int: <required>)` - The versions to destroy. Their data will
   be permanently deleted.

website/content/docs/commands/kv/get.mdx

@@ -18,14 +18,18 @@ with the name but has no data, nothing is returned.
 Retrieve the data of the key "creds":
 
 ```shell-session
-$ vault kv get secret/creds
-====== Metadata ======
-Key              Value
----              -----
-created_time     2019-06-06T06:03:26.595978Z
-deletion_time    n/a
-destroyed        false
-version          5
+$ vault kv get -mount=secret creds
+== Secret Path ==
+secret/data/creds
+
+======= Metadata =======
+Key                Value
+---                -----
+created_time       2022-06-15T20:23:40.067093Z
+custom_metadata    <nil>
+deletion_time      n/a
+destroyed          false
+version            1
 
 ====== Data ======
 Key         Value
@@ -37,7 +41,7 @@ If K/V Version 1 secrets engine is enabled at "secret", the output has no
 metadata since there is no versioning information associated with the data:
 
 ```shell-session
-$ vault kv get secret/creds
+$ vault kv get -mount=secret creds
 ====== Data ======
 Key         Value
 ---         -----
@@ -47,15 +51,12 @@ passcode    my-long-passcode
 Return only the "creds" "passcode" key:
 
 ```shell-session
-$ vault kv get -field=passcode secret/creds
+$ vault kv get -mount=secret -field=passcode creds
 my-long-passcode
 ```
 
 ## Usage
 
-There are no flags beyond the [standard set of flags](/docs/commands)
-included on all commands.
-
 ### Output Options
 
 - `-field` `(string: "")` - Print only the field with the given name. Specifying
@@ -69,5 +70,11 @@ included on all commands.
 
 ### Command Options
 
+- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted. 
+  If specified, the next argument will be interpreted as the secret path. If 
+  this flag is not specified, the next argument will be interpreted as the 
+  combined mount path and secret path, with /data/ automatically inserted for 
+  KV v2 secrets.
+
 - `-version` `(int: 0)` - Specifies the version to return. If not set the
   latest version is returned.

website/content/docs/commands/kv/index.mdx

@@ -12,32 +12,55 @@ The `kv` command groups subcommands for interacting with Vault's key/value
 secrets engine (both [K/V Version 1](/docs/secrets/kv/kv-v1) and [K/V
 Version 2](/docs/secrets/kv/kv-v2).
 
+## Syntax
+
+Option flags for a given subcommand are provided after the subcommand, but before the arguments.
+
+The path to where the secrets engine is mounted can be indicated with the `-mount` flag, such as `vault kv get -mount=secret creds`.
+
+The deprecated path-like syntax can also be used (e.g. `vault kv get secret/creds`), but this should be avoided
+for KV v2, because it is not actually the full API path to the secret 
+(secret/data/foo) and may cause confusion.
+
+~> A `flag provided but not defined: -mount` error means you are using an older version of Vault before the 
+mount flag syntax was introduced. Upgrade to at least Vault 1.11, or refer to previous versions of the docs 
+which only use the old syntax to refer to the mount path.
+
 ## Examples
 
 Create or update the key named "creds" in the K/V Version 2 enabled at "secret"
 with the value "passcode=my-long-passcode":
 
 ```shell-session
-$ vault kv put secret/creds passcode=my-long-passcode
-Key              Value
----              -----
-created_time     2019-06-28T15:53:30.395814Z
-deletion_time    n/a
-destroyed        false
-version          1
+$ vault kv put -mount=secret creds passcode=my-long-passcode
+== Secret Path ==
+secret/data/creds
+
+======= Metadata =======
+Key                Value
+---                -----
+created_time       2022-06-15T20:14:17.107852Z
+custom_metadata    <nil>
+deletion_time      n/a
+destroyed          false
+version            1
 ```
 
 Read this value back:
 
 ```shell-session
-$ vault kv get secret/creds
-====== Metadata ======
-Key              Value
----              -----
-created_time     2019-06-28T15:53:30.395814Z
-deletion_time    n/a
-destroyed        false
-version          1
+$ vault kv get -mount=secret creds
+== Secret Path ==
+secret/data/creds
+
+======= Metadata =======
+Key                Value
+---                -----
+created_time       2022-06-15T20:14:17.107852Z
+custom_metadata    <nil>
+deletion_time      n/a
+destroyed          false
+version            1
 
 ====== Data ======
 Key         Value
@@ -48,37 +71,45 @@ passcode    my-long-passcode
 Get metadata for the key named "creds":
 
 ```shell-session
-$ vault kv metadata get secret/creds
+$ vault kv metadata get -mount=secret creds
+=== Metadata Path ===
+secret/metadata/creds
+
 ========== Metadata ==========
 Key                     Value
 ---                     -----
 cas_required            false
-created_time            2019-06-28T15:53:30.395814Z
+created_time            2022-06-15T20:14:17.107852Z
 current_version         1
+custom_metadata         <nil>
 delete_version_after    0s
 max_versions            0
 oldest_version          0
-updated_time            2019-06-28T15:53:30.395814Z
+updated_time            2022-06-15T20:14:17.107852Z
 
 ====== Version 1 ======
 Key              Value
 ---              -----
-created_time     2019-06-28T15:53:30.395814Z
+created_time     2022-06-15T20:14:17.107852Z
 deletion_time    n/a
 destroyed        false
 ```
 
 Get a specific version of the key named "creds":
 
 ```shell-session
-$ vault kv get -version=1 secret/creds
-====== Metadata ======
-Key              Value
----              -----
-created_time     2019-06-28T15:53:30.395814Z
-deletion_time    n/a
-destroyed        false
-version          1
+$ vault kv get -mount=secret -version=1 creds
+== Secret Path ==
+secret/data/creds
+
+======= Metadata =======
+Key                Value
+---                -----
+created_time       2022-06-15T20:14:17.107852Z
+custom_metadata    <nil>
+deletion_time      n/a
+destroyed          false
+version            1
 
 ====== Data ======
 Key         Value

website/content/docs/commands/kv/metadata.mdx

@@ -38,7 +38,7 @@ provided key.
 Deletes all versions and metadata of the key "creds":
 
 ```shell-session
-$ vault kv metadata delete secret/creds
+$ vault kv metadata delete -mount=secret creds
 Success! Data deleted (if it existed) at: secret/metadata/creds
 ```
 
@@ -52,7 +52,10 @@ the given key name. If no key exists with that name, an error is returned.
 Retrieves the metadata of the key name, "creds":
 
 ```shell-session
-$ vault kv metadata get secret/creds
+$ vault kv metadata get -mount=secret creds
+=== Metadata Path ===
+secret/metadata/creds
+
 ========== Metadata ==========
 Key                     Value
 ---                     -----
@@ -91,14 +94,14 @@ secrets engine or to update key configuration for a specified key.
 Create a key in the K/V v2 with no data at the key "creds":
 
 ```shell-session
-$ vault kv metadata put secret/creds
+$ vault kv metadata put -mount=secret creds
 Success! Data written to: secret/metadata/creds
 ```
 
 Set the maximum number of versions to keep for the key "creds":
 
 ```shell-session
-$ vault kv metadata put -max-versions=5 secret/creds
+$ vault kv metadata put -mount=secret -max-versions=5 creds
 Success! Data written to: secret/metadata/creds
 ```
 
@@ -109,7 +112,7 @@ permanently deleted.
 Require Check-and-Set for the key "creds":
 
 ```shell-session
-$ vault kv metadata put -cas-required secret/creds
+$ vault kv metadata put -mount=secret -cas-required creds
 ```
 
 **NOTE:** When check-and-set is required, the key will require the `cas`
@@ -119,7 +122,7 @@ configuration will be used.
 Set the length of time before a version is deleted for the key "creds":
 
 ```shell-session
-$ vault kv metadata put -delete-version-after="3h25m19s" secret/creds
+$ vault kv metadata put -mount=secret -delete-version-after="3h25m19s" creds
 ```
 
 **NOTE:** If not set, the backend's configured Delete-Version-After is used. If
@@ -154,4 +157,11 @@ be applied to new versions.
   `custom_metadata` field. This can be specified multiple times to add multiple
   pieces of metadata.
 
+- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted. 
+  If specified, the next argument will be interpreted as the secret path. If 
+  this flag is not specified, the next argument will be interpreted as the 
+  combined mount path and secret path, with /data/ automatically inserted for 
+  KV v2 secrets.
+
+
 [duration-godoc]: https://golang.org/pkg/time/#ParseDuration

website/content/docs/commands/kv/patch.mdx

@@ -23,7 +23,11 @@ If you wish to add an additional key-value (`ttl=48h`) to the existing data at
 the key "creds":
 
 ```shell-session
-$ vault kv patch secret/creds ttl=48h
+$ vault kv patch -mount=secret creds ttl=48h
+== Secret Path ==
+secret/data/creds
+
+======= Metadata =======
 Key              Value
 ---              -----
 created_time     2019-06-06T16:46:22.090654Z
@@ -36,20 +40,20 @@ version          6
 the data you wish to add in order to accomplish the same result.
 
 ```shell-session
-$ vault kv put secret/creds ttl=48h passcode=my-long-passcode
+$ vault kv put -mount=secret creds ttl=48h passcode=my-long-passcode
 ```
 
 The data can also be consumed from a file on disk by prefixing with the "@"
 symbol. For example:
 
 ```shell-session
-$ vault kv patch secret/creds @data.json
+$ vault kv patch -mount=secret creds @data.json
 ```
 
 Or it can be read from stdin using the "-" symbol:
 
 ```shell-session
-$ echo "abcd1234" | vault kv patch secret/foo bar=-
+$ echo "abcd1234" | vault kv patch -mount=secret foo bar=-
 ```
 
 ## Usage
@@ -79,3 +83,9 @@ $ echo "abcd1234" | vault kv patch secret/foo bar=-
   version of the secret. This flag will be ignored for the `rw` method.
   Instead, its value will be derived from fetching the current version of the
   secret.
+
+- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted. 
+  If specified, the next argument will be interpreted as the secret path. If 
+  this flag is not specified, the next argument will be interpreted as the 
+  combined mount path and secret path, with /data/ automatically inserted for 
+  KV v2 secrets.