vault kv metadata: KV v2 Versions and Settings
vault kv metadata manages the version history and settings of a KV v2 secret, including permanent deletion of the whole secret.
KV v2 keeps version metadata separate from the data. metadata is how you see all versions, cap retention with max_versions, or remove a secret entirely (not just one version).
What it does
vault kv metadata has subcommands: get shows all versions and their state, put sets options like max_versions and cas_required, and delete removes the secret along with every version and its metadata. It operates on the metadata/ API path of a KV v2 mount.
Common usage
vault kv metadata get secret/ci/db
# cap to 5 versions and require CAS
vault kv metadata put -max-versions=5 -cas-required=true secret/ci/db
# remove the secret and ALL versions permanently
vault kv metadata delete secret/ci/dbOptions
| Flag | What it does |
|---|---|
| get / put / delete | Read, configure, or fully remove the secret metadata |
| -max-versions=<n> | Number of versions to retain |
| -cas-required=true | Require check-and-set on every write |
| -delete-version-after=<dur> | Auto-delete versions after a duration |
| -mount=<name> | Specify the KV v2 mount explicitly |
In CI
Use metadata delete (not kv delete) when teardown must fully remove a secret; kv delete only soft-deletes the latest version. Set max_versions so a chatty pipeline that rewrites a secret on every run does not grow version history without bound.
Common errors in CI
"No value found at secret/metadata/ci/db" means the secret does not exist or the mount is KV v1 (no metadata API). "permission denied" means the policy lacks access to the metadata/ path; metadata operations need their own capabilities distinct from data/.