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 create and update 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            falsecreated_time            2024-11-13T21:51:50.898782695Zcurrent_version         4custom_metadata         <nil>delete_version_after    0smax_versions            5oldest_version          0updated_time            2024-11-14T22:32:42.29534643Z ====== Version 1 ======Key              Value---              -----created_time     2024-11-13T21:51:50.898782695Zdeletion_time    n/adestroyed        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