Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท Secrets Engines

KV Version 2 and Secret Versioning

Learn KV version 2 features: versions, rollback, delete versus destroy, undelete, max_versions, check-and-set and custom metadata, with a runnable versioned store model.

The KV secrets engine comes in two versions. KV v1 stores one value per path: a write overwrites the old one. KV v2 keeps a history of versions per secret, supports soft deletion and recovery, and adds optimistic locking. KV v2 is what the dev server mounts at secret/, and it is the usual choice today.

This lesson explains versioning and deletion semantics, the commands that go with them, and builds a runnable model of a versioned store with check-and-set.

Vault is not available here; commands are read-only, no output is invented. The Python store is a model of the documented behaviour, simplified.

v1 versus v2

KV v1 KV v2
History None: overwrites Many versions per secret
Delete Permanent Soft delete, undelete, or permanent destroy
Patch No Yes
Check-and-set No Yes
Custom metadata No Yes
API shape /v1/kv/path /v1/kv/data/path, /v1/kv/metadata/path
Speed Slightly faster, fewer storage writes A bit more overhead

Enable v2 explicitly with vault secrets enable -path=kv -version=2 kv or the alias kv-v2. An existing v1 mount can be upgraded with vault kv enable-versioning kv/; the reverse is not possible.

Versions

Each write creates the next version number (1, 2, 3, ...).

Terminal
vault kv put -mount=secret app/db password=one         # version 1
vault kv put -mount=secret app/db password=two         # version 2
vault kv get -mount=secret -version=1 app/db           # read an old version
vault kv rollback -version=1 -mount=secret app/db      # writes v1's data as a NEW version 3
vault kv metadata get -mount=secret app/db             # versions, timestamps, settings

By default KV v2 keeps the last 10 versions; older ones are removed automatically. Change it per mount (vault write secret/config max_versions=20) or per secret (vault kv metadata put -max-versions=5 ...).

Delete, undelete, destroy

Terminal
vault kv delete   -mount=secret app/db                  # soft-delete the latest version
vault kv delete   -versions=2,3 -mount=secret app/db
vault kv undelete -versions=2 -mount=secret app/db      # bring it back
vault kv destroy  -versions=1 -mount=secret app/db      # permanent: data gone
vault kv metadata delete -mount=secret app/db           # removes ALL versions and metadata

A soft-deleted version keeps its data but cannot be read until undeleted. A destroyed version is gone for good. Because deletes are soft by default, KV v2 forgives mistakes, but remember that soft-deleted data still exists in storage until destroyed, which matters if you need to erase a leaked secret for real.

stateDiagram-v2
    [*] --> Active: put
    Active --> Deleted: delete
    Deleted --> Active: undelete
    Active --> Destroyed: destroy
    Deleted --> Destroyed: destroy
    Destroyed --> [*]

Each version moves through these states independently.

Check-and-set

Two writers who read version 3 and both write could silently overwrite each other. Check-and-set (CAS) prevents this: a write states the version it expects the secret to currently be at, and Vault rejects it if the current version is different.

Terminal
vault kv put -cas=3 -mount=secret app/db password=four   # only succeeds if current version is 3
vault write secret/config cas_required=true              # make CAS mandatory for the mount

Use -cas=0 to mean "only if the secret does not exist yet".

A versioned store you can run

Python A model of KV v2 with soft delete, destroy and CAS

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

rollback copies old data into a new version instead of rewinding, so history is never rewritten. And with max_versions=3, version 1 was pruned as soon as version 4 existed, so it is already gone.

Custom metadata

Metadata is not secret and is stored with the secret's metadata, useful for ownership and rotation tracking:

Terminal
vault kv metadata put -mount=secret \
  -custom-metadata=owner=payments -custom-metadata=rotate_by=2026-12-01 app/db

Policies for KV v2 must name secret/data/... for reads and writes, secret/metadata/... for listing and metadata, and secret/delete/..., secret/undelete/..., secret/destroy/... for those operations. That separation lets you grant an application read access while keeping destroy for administrators.

Checking which API path a CLI call uses

Python CLI action to KV v2 policy path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does vault kv rollback -version=1 do?

    Rollback creates a new latest version containing the old data; history is not rewritten.
  2. 2. What is the difference between delete and destroy?

    undelete can restore a soft-deleted version. Destroy cannot be undone.
  3. 3. What does -cas=0 mean on a put?

    CAS 0 expresses "create only"; any other number must match the current version.
  4. 4. By default, how many versions does KV v2 keep per secret?

    The default max_versions is 10; older versions are pruned.

Summary

  • KV v2 keeps versions (10 by default), supports patch, rollback, soft delete, undelete and destroy.
  • rollback writes old data as a new version; destroy is permanent.
  • Check-and-set makes concurrent writers safe; cas_required makes it mandatory.
  • Custom metadata tracks ownership without being secret.
  • Policies must name data/, metadata/, delete/, undelete/ and destroy/ paths separately.

Next: Cubbyhole and Response Wrapping