[DOCS] Refresh kv docs (#28919)

* refresh kv docs * apply feedback and add missing API instructions
hashicorp · Nov 16, 2024 · cb0448a · cb0448a
1 parent 52ba156
commit cb0448a
Show file tree

Hide file tree

Showing 26 changed files with 2,078 additions and 632 deletions.
diff --git a/website/content/docs/secrets/kv/kv-v2.mdx b/website/content/docs/secrets/kv/kv-v2.mdx
diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/custom-metadata.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/custom-metadata.mdx
@@ -0,0 +1,149 @@
+---
+layout: docs
+page_title: Write custom metadata
+description: >-
+   Write custom metadata fields to your kv v2 plugin.
+---
+
+# Write custom metadata in key/value v2 
+
+Write custom metadata to a `kv` v2 secret path.
+
+<Tip title="Assumptions">
+
+- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). 
+- Your authentication token has `create` and `update` permissions for the `kv`
+  v2 plugin.
+
+</Tip>
+
+<Tabs>
+
+<Tab heading="CLI" group="cli">
+
+Use [`vault kv metadata put`](/vault/docs/command/kv/metadata) to set custom
+metadata fields for a `kv` mount path. Repeat the `-custom-metadata` flag for
+each key/value metadata entry:
+
+```shell-session
+$ vault kv metadata put                \
+   -custom-metadata <key_value_pair>   \
+   -mount <mount_path>                 \
+   <secret_path>
+```
+
+For example: 
+
+<CodeBlockConfig hideClipboard="true">
+
+```shell-session
+$ vault kv metadata put                                              \
+   -custom-metadata "use=API keys for different dev environments"   \
+   -custom-metadata "renew-date=2026-11-14"                          \
+   -mount shared                                                     \
+   dev/square-api
+
+Success! Data written to: shared/metadata/dev/square-api
+```
+</CodeBlockConfig>
+
+
+The `custom_metadata` metadata field now includes a map with the two custom
+fields:
+
+<CodeBlockConfig hideClipboard="true" highlight="14">
+
+```shell-session
+$ vault kv metadata get -mount shared dev/square-api
+
+======== Metadata Path ========
+shared/metadata/dev/square-api
+
+========== Metadata ==========
+Key                     Value
+---                     -----
+cas_required            false
+created_time            2024-11-13T21:51:50.898782695Z
+current_version         9
+custom_metadata         map[use:API keys for different dev environments renew-date:2026-11-14]
+delete_version_after    0s
+max_versions            10
+oldest_version          4
+updated_time            2024-11-15T03:10:26.749233814Z
+
+====== Version 1 ======
+Key              Value
+---              -----
+created_time     2024-11-13T21:51:50.898782695Z
+deletion_time    n/a
+destroyed        false
+```
+
+</CodeBlockConfig>
+
+</Tab>
+
+<Tab heading="GUI" group="gui">
+
+@include 'gui-page-instructions/select-kv-mount.mdx'
+
+- Click through the path segments to select the relevant secret path.
+- Select the **Metadata** tab.
+- Click **Edit metadata >**.
+- Set a new key name and value under **Custom metadata**.
+- Use the **Add** button to set additional key/value pairs.
+- Click **Update**.
+
+![Partial screenshot of the Vault GUI showing the "Edit Secret Metadata" screen](/img/gui/kv/custom-metadata.png)
+
+</Tab>
+
+<Tab heading="API" group="api">
+
+1. Create a JSON file with the metadata you want to write to the your `kv` v2
+   plugin. Use the `custom_metadata` field to define the custom metadata fields
+   and initial values.
+
+1. Make a `POST` call to
+   [`/{plugin_mount_path}/metadata/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#create-update-metadata)
+   with the JSON data file:
+    ```shell-session
+    $ curl                                      \
+      --request POST                            \
+      --header "X-Vault-Token: ${VAULT_TOKEN}"  \
+      --data @metadata.json                     \
+      ${VAULT_ADDR}/v1/<plugin_mount_path>/metadata/<secret_path>
+    ```
+
+For example:
+
+<CodeBlockConfig hideClipboard="true">
+
+```json
+{
+  "custom_metadata": {
+    "use": "API keys for different dev environments",
+    "renew-date": "2026-11-14"
+  }
+}
+```
+
+</CodeBlockConfig>
+
+<CodeBlockConfig hideClipboard="true">
+
+```shell-session
+$ curl                                       \
+    --request POST                           \
+    --header "X-Vault-Token: ${VAULT_TOKEN}" \
+    --data @metadata.json                    \
+    ${VAULT_ADDR}/v1/shared/metadata/dev/square-api
+```
+
+`/{plugin_mount_path}/metadata/{secret_path}` does not return data on success.
+
+</CodeBlockConfig>
+
+</Tab>
+
+</Tabs>
diff --git a/website/content/docs/secrets/kv/kv-v2/cookbook/delete-data.mdx b/website/content/docs/secrets/kv/kv-v2/cookbook/delete-data.mdx
@@ -0,0 +1,144 @@
+---
+layout: docs
+page_title: Soft delete data
+description: >-
+   Use soft deletes to control the lifecycle of versioned key/value data in the
+   kv v2 plugin.
+---
+
+# Soft delete key/value data
+
+Use soft deletes to flag data at a secret path as unavailable while leaving the
+data recoverable. You can revert soft deletes as long as the `destroyed` field
+is `false` in the metadata.
+
+<Tip title="Assumptions">
+
+- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). 
+- Your authentication token has `create` and `update` permissions for the `kv`
+  v2 plugin.
+
+</Tip>
+
+<Tabs>
+
+<Tab heading="CLI" group="cli">
+
+Use [`vault kv delete`](/vault/docs/command/kv/delete) with the `-versions` flag to
+soft delete one or more version of key/value data and set `deletion_time` in the
+metadata:
+
+```shell-session
+$ vault kv delete               \
+   -mount <mount_path>          \
+   -versions <target_versions>  \
+   <secret_path>
+```
+
+For example:
+
+<CodeBlockConfig hideClipboard="true">
+
+```shell-session
+$ vault kv delete -mount shared -versions 1,4 dev/square-api
+
+Success! Data deleted (if it existed) at: shared/data/dev/square-api
+```
+
+</CodeBlockConfig>
+
+The `deletion_time` metadata field for versions 1 and 4 now has the timestamp
+of when Vault marked the versions as deleted:
+
+<CodeBlockConfig hideClipboard="true" highlight="22,31">
+
+```shell-session
+$ vault kv metadata get -mount shared dev/square-api
+
+======== Metadata Path ========
+shared/metadata/dev/square-api
+
+========== Metadata ==========
+Key                     Value
+---                     -----
+cas_required            false
+created_time            2024-11-13T21:51:50.898782695Z
+current_version         4
+custom_metadata         <nil>
+delete_version_after    0s
+max_versions            5
+oldest_version          0
+updated_time            2024-11-14T22:32:42.29534643Z
+
+====== Version 1 ======
+Key              Value
+---              -----
+created_time     2024-11-13T21:51:50.898782695Z
+deletion_time    2024-11-15T00:45:04.057772212Z
+destroyed        false
+
+...
+
+====== Version 4 ======
+Key              Value
+---              -----
+created_time     2024-11-14T22:32:42.29534643Z
+deletion_time    2024-11-15T00:45:04.057772712Z
+destroyed        false
+```
+
+
+</CodeBlockConfig>
+
+
+</Tab>
+
+<Tab heading="GUI" group="gui">
+
+@include 'gui-page-instructions/select-kv-mount.mdx'
+
+- Click through the path segments to select the relevant secret path.
+- Select the appropriate data version from the **Version** dropdown.
+- Click **Delete**.
+- Select **Delete this version** to delete the selected version or
+  **Delete latest version** to delete the most recent data.
+- Click **Confirm**.
+
+![Partial screenshot of the Vault GUI showing the "Delete version?" confirmation modal for data at the path dev/square-api](/img/gui/kv/delete-version.png)
+
+</Tab>
+
+<Tab heading="API" group="api">
+
+Make a `POST` call to
+[`/{plugin_mount_path}/delete/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#delete-secret-versions)
+with the data versions you want to soft delete:
+
+```shell-session
+$ curl                                       \
+   --request POST                            \
+   --header "X-Vault-Token: ${VAULT_TOKEN}"  \
+   --data '{"versions":[<target_versions>]}  \
+   ${VAULT_ADDR}/v1/<plugin_mount_path>/delete/<secret_path>
+```
+
+For example:
+
+<CodeBlockConfig hideClipboard="true">
+
+```shell-session
+$ curl                                       \
+    --request POST                           \
+    --header "X-Vault-Token: ${VAULT_TOKEN}" \
+    --data '{"versions":[5,8]}'              \
+    ${VAULT_ADDR}/v1/shared/delete/dev/square-api | jq
+
+```
+
+`/{plugin_mount_path}/delete/{secret_path}` does not return data on success.
+
+</CodeBlockConfig>
+
+</Tab>
+
+</Tabs>