Version
An immutable revision under one KV v2 key.
Chapter contract
Prerequisites:
Chapter 5 complete and the shared KV v2 key created by bootstrap.
User-visible outcome:
Priya can retrieve one KV field into protected temporary storage and verify version metadata only.
Learning objectives
- Read one KV v2 field into a mode-0600 runtime file.
- Understand versions, check-and-set, soft delete, undelete, and destruction.
- Keep rendered runtime files temporary and observable only through metadata.
Consumer flow
Ownership boundary
| Owner | Consumer-facing responsibility |
|---|---|
| You own | Defines consumption, validation, reload, and stop-using behavior. |
| Platform team owns | Provides trusted runtime identity, protected delivery, network, and telemetry. |
| Vault owns | Operates auth mounts, policies, engines, audit, and recovery. |
Core concepts
Check-and-set
A precondition preventing overwrite of an unexpected version.
Soft delete
Hides selected versions while retaining recoverable data.
Metadata delete
Permanently removes all versions and metadata.
Commands and configuration
source learn-vault/.runtime/learner.env
umask 077
vault kv get -field=feature_mode lockbox-kv/orders-api > learn-vault/.runtime/feature-mode
test "$(stat -f '%Lp' learn-vault/.runtime/feature-mode)" = 600
vault kv metadata get -format=json lockbox-kv/orders-api | jq '{current_version:.data.current_version}'Secret-safety stop
Stop: Selecting one field reduces exposure, but the output is still secret material. Redirect it; never echo it to verify.
Failure drill
| Symptom | The application reads an older value after rotation. |
|---|---|
| Likely causes | Pinned version, stale Agent render, no process reload, or overlong cache. |
| Inspect safely | Compare metadata version with recorded consumer version and render time. |
| Do not print | Old or new values, rendered files, or process environment. |
Break it / fix it
Break it: Keep a rendered KV field after verification.
Show diagnosis and fix
Fix it: Remove the runtime file and rely on version and freshness metadata for evidence.
Escalate with time, endpoint, auth path, role, mount, namespace when relevant, status code, request ID, and sanitized error class. Never attach a credential or response body.
Try it
Bootstrap boundary
labs/bootstrap owns the disposable server, auth mounts, policies, roles, and engines; learner actions begin after setup.
Cost:
$0; local containers only
Starting state:
Run labs/bootstrap/setup.sh and source .runtime/learner.env unless the chapter lab says AppRole alone is sufficient.
User actions:
Run the dedicated KV consumer script, verify protected delivery and version metadata, then remove the runtime field.
cd learn-vault/labs/kv-v2
./read-field.sh
./cleanup.shSuccess criteria:
Complete every item in the Verify section using metadata-only evidence; no secret value appears in terminal output or tracked files.
Troubleshooting:
Use the Failure drill and Break it / fix it evidence fields. Stop before broadening policy, weakening identity or TLS checks, or copying secret-bearing diagnostics.
Verify
- The file is non-empty and mode 0600 while in use.
- Metadata reports a current version without stored fields.
- The runtime file is removed.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
Remove renders, unset the token, and exclude .runtime from backups and support bundles.
Project Lockbox increment
orders-api consumes a minimal field and records only its KV version and reload time.
Quick check
Does versioning replace recovery policy?
No. It helps local recovery but does not define retention or disaster recovery.
Why use check-and-set?
It prevents overwriting a newer revision the writer did not read.
Is mode 0600 sufficient?
No. Process ownership, backups, crash tools, and copies still matter.
What can readiness expose?
Version and freshness, never value.
Gotchas
- Environment variables can leak through diagnostics and child processes.
- Soft-deleted versions still exist until destroyed.
- Backup agents may copy runtime paths unless excluded.
Recap and next
KV v2 provides versioned storage; consumers still own narrow retrieval, protected delivery, reload, and deletion.