KV (v1 and v2)

KV is the most-used secret engine in Vault. The implementation is not in this repository — it's in hashicorp/vault-plugin-secrets-kv, imported as a built-in via helper/builtinplugins/registry.go. This page documents how it integrates with Vault and the on-the-wire shapes the rest of the system depends on.

Purpose

Store user-supplied values keyed by path. Two versions:

• KV v1 — overwrite-on-write, no history. Behavior matches the original Vault generic engine.
• KV v2 — versioned with metadata, soft-delete, undelete, destroy, custom metadata. The default for new mounts.

A KV mount is just a logical.Backend that handles its own paths; Vault's router and ACL layer treat it like any other secret engine.

Wire shapes

For v1, vault read secret/foo returns the value directly:

{ "data": { "key": "value" } }

For v2, the value lives under data/<path> and metadata under metadata/<path>:

{
  "data": {
    "data": { "key": "value" },
    "metadata": { "version": 1, "created_time": "..." }
  }
}

The CLI hides the doubling-up: vault kv put secret/foo key=value is the user-friendly form, and vault kv get secret/foo strips the inner wrapper.

CLI

Eleven verbs spread across command/kv*.go:

| Command | What | | ---------------------------- | --------------------------------------------- | ------ | ------ | ----------------------- | | vault kv put | Write or update a value. | | vault kv get | Read a value. | | vault kv list | List subkeys. | | vault kv delete | Soft-delete a v2 version (or hard delete v1). | | vault kv destroy | Permanently destroy a v2 version. | | vault kv undelete | Restore a soft-deleted v2 version. | | vault kv patch | Merge into an existing v2 value. | | vault kv rollback | Promote an older v2 version to current. | | vault kv metadata get | put | delete | patch | v2 metadata operations. | | vault kv enable-versioning | Upgrade an existing v1 mount to v2. |

The shared helpers are in command/kv_helpers.go.

Versioning, deletion, destruction

For v2, every write produces a new version. Reads default to the latest non-destroyed version; -version=N selects a specific one. Deletes mark a version soft-deleted (recoverable via kv undelete), kv destroy removes the value irretrievably (only metadata remains). kv metadata delete removes everything including history.

max_versions and delete_version_after (TTL-based auto-prune) are configurable per path.

Per-path constraints

KV v2 supports cas (compare-and-swap) writes: vault kv put -cas=N writes only if the current version is N. This lets multiple writers serialize without an explicit lock.

custom_metadata lets clients attach key/value annotations to a KV path that aren't subject to the regular secret data lifecycle.

Integration points

• Mounted as a built-in via helper/builtinplugins/registry.go.
• Routed and authorized like any other secret engine (Router and mounts, Policy and ACL).
• The audit broker treats data fields as sensitive and HMACs them by default.
• The event bus (vault/eventbus/) emits kv-v2/data-write, kv-v2/data-delete, kv-v2/metadata-delete events.
• The UI's secret-engine flows know about both v1 and v2 so the user-facing UX hides the differences.

Entry points for modification

The KV implementation isn't here, but plenty of Vault touches it:

• CLI verbs: command/kv_*.go.
• API helpers: api/kv.go, api/kv_v1.go, api/kv_v2.go.
• Audit treatment of v2 paths: audit/headers.go and the path-aware filter.
• Event types: vault/eventbus/ consumers.