Set max data versions in key/value v2

Limit the number of active versions for a kv v2 secret path so Vault permanently deletes (destroys) older data versions automatically.

Assumptions

You have set up a kv v2 plugin.
Your authentication token has metadata permissions for the kv v2 plugin.

Use vault kv metadata put to change the max number of versions allowed for a kv mount path:

$ vault kv metadata put          \
   -max-versions <max_versions>  \
   -mount <mount_path>           \
   <secret_path>

For example:

$ vault kv metadata put \
   -max-versions 5      \
   -mount shared        \
   dev/square-api

Success! Data written to: shared/metadata/dev/square-api

Vault now auto-deletes data when the number of versions exceeds 5:

$ 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    n/a
destroyed        false

Open the data page for your kv plugin:
1. Open the GUI for your Vault instance.
2. Login under the namespace for the plugin or select the namespace from the selector at the bottom of the left-hand menu and re-authenticate.
3. Select Secrets Engines from the left-hand menu.
4. Select the mount path for your kv plugin.

Click through the path segments to select the relevant secret path.
Select the Metadata tab.
Click Edit metadata >.
Update the Maximum number of versions field.
Click Update.

Partial screenshot of the Vault GUI showing the "Edit Secret Metadata" screen

Create a JSON file with the metadata field max_versions set to the maximum number of versions you want to allow.

Make a POST call to /{plugin_mount_path}/metadata/{secret_path} with the JSON data file:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data @metadata.json                     \
  ${VAULT_ADDR}/v1/<plugin_mount_path>/metadata/<secret_path>

For example:

{
  "max_versions": 10
}

$ curl                                       \
    --request POST                           \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --data @metadata.json                    \
    ${VAULT_ADDR}/v1/shared/metadata/dev/square-api