From 68744f8c7c2660d977ee3691b38079e0e5b2de22 Mon Sep 17 00:00:00 2001
From: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com>
Date: Wed, 10 May 2023 18:21:26 -0400
Subject: [PATCH] Add requested generated secret example (#20556)

* Add requested generated secret example

* Fix code block types

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

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

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

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

---------

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>
---
 website/content/docs/secrets/kv/kv-v1.mdx |  51 +++++++++--
 website/content/docs/secrets/kv/kv-v2.mdx | 101 +++++++++++++++++++---
 2 files changed, 133 insertions(+), 19 deletions(-)

diff --git a/website/content/docs/secrets/kv/kv-v1.mdx b/website/content/docs/secrets/kv/kv-v1.mdx
index e7e456b44fa6..ba010881f344 100644
--- a/website/content/docs/secrets/kv/kv-v1.mdx
+++ b/website/content/docs/secrets/kv/kv-v1.mdx
@@ -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
diff --git a/website/content/docs/secrets/kv/kv-v2.mdx b/website/content/docs/secrets/kv/kv-v2.mdx
index edfebe80e39b..6f26ba786cc7 100644
--- a/website/content/docs/secrets/kv/kv-v2.mdx
+++ b/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,7 +83,7 @@ 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"]
 }
@@ -89,7 +91,7 @@ path "secret/dev/team-1/*" {
 
 Should be changed to:
 
-```
+```plaintext
 path "secret/data/dev/team-1/*" {
   capabilities = ["create", "update", "read"]
 }
@@ -98,7 +100,7 @@ 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"]
 }
@@ -106,7 +108,7 @@ path "secret/data/dev/team-1/*" {
 
 To allow the policy to delete any version of a key:
 
-```
+```plaintext
 path "secret/delete/dev/team-1/*" {
   capabilities = ["update"]
 }
@@ -114,7 +116,7 @@ path "secret/delete/dev/team-1/*" {
 
 To allow a policy to undelete data:
 
-```
+```plaintext
 path "secret/undelete/dev/team-1/*" {
   capabilities = ["update"]
 }
@@ -122,7 +124,7 @@ path "secret/undelete/dev/team-1/*" {
 
 To allow a policy to destroy versions:
 
-```
+```plaintext
 path "secret/destroy/dev/team-1/*" {
   capabilities = ["update"]
 }
@@ -130,7 +132,7 @@ path "secret/destroy/dev/team-1/*" {
 
 To allow a policy to list keys:
 
-```
+```plaintext
 path "secret/metadata/dev/team-1/*" {
   capabilities = ["list"]
 }
@@ -138,7 +140,7 @@ path "secret/metadata/dev/team-1/*" {
 
 To allow a policy to view metadata for each version:
 
-```
+```plaintext
 path "secret/metadata/dev/team-1/*" {
   capabilities = ["read"]
 }
@@ -146,7 +148,7 @@ path "secret/metadata/dev/team-1/*" {
 
 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