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/.
Using this in CI
Cloud CLIs behave differently on a runner than on your laptop. They assume no interactive terminal, no cached credentials, and no browser for device-code flows, so the same command that works locally can hang or fail on a runner.
- Authenticate with a short-lived OIDC token rather than a long-lived static key. GitHub Actions can exchange
id-token: writefor cloud credentials with no stored secret. - Always pass the non-interactive flag. Most cloud CLIs will otherwise prompt and hang until the job times out.
- Pin the CLI version. Cloud CLIs change output formats between minor releases, and any script parsing that output will break silently.
- Set the output format explicitly (
--output json) rather than relying on the default, which can differ by version and configuration profile.