backport of commit 68744f8 (hashicorp#20560)

Co-authored-by: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com>

website/content/docs/secrets/kv/kv-v1.mdx

@@ -9,7 +9,7 @@ description: The KV secrets engine can store arbitrary secrets.
 The `kv` secrets engine is used to store arbitrary secrets within the
 configured physical storage for Vault.
 
-Writing to a key in the `kv` backend will replace the old value; sub-fields are
+Writing to a key in the `kv` backend will replace the earlier value; sub-fields are
 not merged together.
 
 Key names must always be strings. If you write non-string values directly via
@@ -28,8 +28,8 @@ secret's path.
 
 To enable a version 1 kv store:
 
-```
-vault secrets enable -version=1 kv
+```shell-session
+$ vault secrets enable -version=1 kv
 ```
 
 ## Usage
@@ -40,14 +40,14 @@ allows for writing keys with arbitrary values.
 
 1. Write arbitrary data:
 
-   ```text
+   ```shell-session
    $ vault kv put kv/my-secret my-value=s3cr3t
    Success! Data written to: kv/my-secret
    ```
 
 1. Read arbitrary data:
 
-   ```text
+   ```shell-session
    $ vault kv get kv/my-secret
    Key                 Value
    ---                 -----
@@ -56,7 +56,7 @@ allows for writing keys with arbitrary values.
 
 1. List the keys:
 
-   ```text
+   ```shell-session
    $ vault kv list kv/
    Keys
    ----
@@ -65,11 +65,50 @@ allows for writing keys with arbitrary values.
 
 1. Delete a key:
 
-   ```
+   ```shell-session
    $ vault kv delete kv/my-secret
    Success! Data deleted (if it existed) at: kv/my-secret
    ```
 
+You can also use [Vault's password policy](/vault/docs/concepts/password-policies) feature to generate arbitrary values.
+
+1. Write a password policy:
+
+   ```shell-session
+   $ vault write sys/policies/password/example policy=-<<EOF
+
+     length=20
+
+     rule "charset" {
+       charset = "abcdefghij0123456789"
+       min-chars = 1
+     }
+
+     rule "charset" {
+       charset = "!@#$%^&*STUVWXYZ"
+       min-chars = 1
+     }
+
+   EOF
+   ```
+
+1. Write data using the `example` policy:
+
+   ```shell-session
+   $ vault kv put kv/my-generated-secret \
+       password=$(vault read -field password sys/policies/password/example/generate)
+   ```
+
+1. Read the generated data:
+
+   ```shell-session
+   $ vault kv get kv/my-generated-secret
+   ====== Data ======
+   Key         Value
+   ---         -----
+   password    ^dajd609Xf8Zhac$dW24
+   ```
+
 ## TTLs
 
 Unlike other secrets engines, the KV secrets engine does not enforce TTLs

website/content/docs/secrets/kv/kv-v2.mdx

@@ -63,7 +63,9 @@ $ cat payload.json
       "version": "2"
   }
 }
+```
 
+```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     --request POST \
@@ -81,15 +83,15 @@ differently.
 Writing and reading versions are prefixed with the `data/` path. This policy
 that worked for the version 1 kv:
 
-```
+```plaintext
 path "secret/dev/team-1/*" {
   capabilities = ["create", "update", "read"]
 }
 ```
 
 Should be changed to:
 
-```
+```plaintext
 path "secret/data/dev/team-1/*" {
   capabilities = ["create", "update", "read"]
 }
@@ -98,55 +100,55 @@ path "secret/data/dev/team-1/*" {
 There are different levels of data deletion for this backend. To grant a policy
 the permissions to delete the latest version of a key:
 
-```
+```plaintext
 path "secret/data/dev/team-1/*" {
   capabilities = ["delete"]
 }
 ```
 
 To allow the policy to delete any version of a key:
 
-```
+```plaintext
 path "secret/delete/dev/team-1/*" {
   capabilities = ["update"]
 }
 ```
 
 To allow a policy to undelete data:
 
-```
+```plaintext
 path "secret/undelete/dev/team-1/*" {
   capabilities = ["update"]
 }
 ```
 
 To allow a policy to destroy versions:
 
-```
+```plaintext
 path "secret/destroy/dev/team-1/*" {
   capabilities = ["update"]
 }
 ```
 
 To allow a policy to list keys:
 
-```
+```plaintext
 path "secret/metadata/dev/team-1/*" {
   capabilities = ["list"]
 }
 ```
 
 To allow a policy to view metadata for each version:
 
-```
+```plaintext
 path "secret/metadata/dev/team-1/*" {
   capabilities = ["read"]
 }
 ```
 
 To allow a policy to permanently remove all versions and metadata for a key:
 
-```
+```plaintext
 path "secret/metadata/dev/team-1/*" {
   capabilities = ["delete"]
 }
@@ -207,11 +209,11 @@ real path).
 
 1. Write another version, the previous version will still be accessible. The
    `-cas` flag can optionally be passed to perform a check-and-set operation. If
-   not set the write will be allowed. In order for a write to be successful, `cas` must be set to 
-  the current version of the secret. If set to 0 a write will only be allowed if 
-  the key doesn’t exist as unset keys do not have any version information. Also 
+   not set the write will be allowed. In order for a write to be successful, `cas` must be set to
+  the current version of the secret. If set to 0 a write will only be allowed if
+  the key doesn’t exist as unset keys do not have any version information. Also
   remember that soft deletes do not remove any underlying version data from storage.
-  In order to write to a soft deleted key, the cas parameter must match the key's 
+  In order to write to a soft deleted key, the cas parameter must match the key's
   current version.
 
    ```shell-session
@@ -339,6 +341,77 @@ real path).
    bar         b
    ```
 
+You can also use [Vault's password policy](/vault/docs/concepts/password-policies) feature to generate arbitrary values.
+
+1. Write a password policy:
+
+   ```shell-session
+   $ vault write sys/policies/password/example policy=-<<EOF
+
+     length=20
+
+     rule "charset" {
+       charset = "abcdefghij0123456789"
+       min-chars = 1
+     }
+
+     rule "charset" {
+       charset = "!@#$%^&*STUVWXYZ"
+       min-chars = 1
+     }
+
+   EOF
+   ```
+
+1. Write data using the `example` policy:
+
+   ```shell-session
+   $ vault kv put -mount=secret my-generated-secret \
+       password=$(vault read -field password sys/policies/password/example/generate)
+   ```
+
+   **Example output:**
+
+   <CodeBlockConfig hideClipboard>
+
+   ```plaintext
+   ========= Secret Path =========
+   secret/data/my-generated-secret
+
+   ======= Metadata =======
+   Key                Value
+   ---                -----
+   created_time       2023-05-10T14:32:32.37354939Z
+   custom_metadata    <nil>
+   deletion_time      n/a
+   destroyed          false
+   version            1
+   ```
+
+   </CodeBlockConfig>
+
+1. Read the generated data:
+
+   ```shell-session
+   $ vault kv get -mount=secret my-generated-secret
+   ========= Secret Path =========
+   secret/data/my-generated-secret
+
+   ======= Metadata =======
+   Key                Value
+   ---                -----
+   created_time       2023-05-10T14:32:32.37354939Z
+   custom_metadata    <nil>
+   deletion_time      n/a
+   destroyed          false
+   version            1
+
+   ====== Data ======
+   Key         Value
+   ---         -----
+   password    !hh&be1e4j16dVc0ggae
+   ```
+
 ### Deleting and Destroying Data
 
 When deleting data the standard `vault kv delete` command will perform a
@@ -517,7 +590,9 @@ See the commands below for more information:
    ```shell-session
    $ vault kv metadata patch -mount=secret -custom-metadata=foo=def my-secret
    Success! Data written to: secret/metadata/my-secret
+   ```
 
+   ```shell-session
    $ vault kv get -mount=secret my-secret
    ====== Metadata ======
    Key              Value