KeyValue Secrets Engine

Vault's Key/Value (KV) Secrets Engine securely stores static secrets—API keys, certificates, credentials—that Vault doesn’t generate dynamically. You can retrieve these secrets via UI, CLI, or API and integrate with tools like Terraform, Jenkins, or GitLab CI/CD.

Why Use KV for Static Secrets

• Centralized management of non-rotating secrets
• Integration with CI/CD and automation tools
• Granular access control through Vault policies
• 256-bit AES encryption at rest

KV Engine Versions: v1 vs. v2

Reading from v2 returns the latest version unless you specify another version.

Enabling the KV Engine

KV v2 is not enabled by default in production.

Via UI

1. Go to Secrets > Enable new engine
2. Select Key/Value
3. Set Mount path (default kv) and choose version
4. (Optional) Add description, tune max versions or CAS, configure deletion

Via CLI

Enable KV v1 at kv/ (default):

vault secrets enable kv
# Success! Enabled the kv secrets engine at: kv/

Enable KV v1 at a custom path:

vault secrets enable -path=training kv
# Success! Enabled the kv secrets engine at: training/

List mounts with version info:

vault secrets list -detailed
# Path       Plugin    Accessor       Options
# ----       ------    --------       -------
# cubbyhole/ cubbyhole cubbyhole_xyz  map[]
# kv/        kv        kv_abc123      map[]        # v1
# training/  kv        kv_def456      map[]        # v1

Enable KV v2 at a new mount:

vault secrets enable -path=kv-v2 -version=2 kv
# Success! Enabled the kv-v2 secrets engine at: kv-v2/

Verify mounts:

vault secrets list -detailed
# kv-v2/ kv kv_ghi789 map[version:2]   # v2

Enable versioning on an existing mount:

vault kv enable-versioning training/
# Success! Tuned the secrets engine at: training/

Organizing Secrets with KV Paths

Plan a path hierarchy to simplify policies and discovery.

Option A: Single mount with folders

kv/
├── cloud/
│   ├── aws/
│   ├── gce/
│   └── …
├── automation/
│   ├── dev/
│   ├── prod/
│   └── …
└── data/
    ├── warehousing/
    └── analytics/

Option B: Multiple mounts per domain

Path Example: apps/

apps/
└─ aws/
   ├─ prod/   ← { user, password, API }
   └─ dev/    ← { certificate, private_key }

• Mount: apps/
• Secret path: apps/aws/prod
• Read: vault kv get apps/aws/prod

KV v2 Metadata & API Prefixes

KV v2 adds metadata (versions, timestamps, deletion status). It introduces two API prefixes:

• data/ – stores secret values
• metadata/ – tracks version history

Mounting v2 at cloud/ yields:

• /v1/cloud/data/... for secret operations
• /v1/cloud/metadata/... for metadata

The CLI abstracts these, so vault kv get cloud/apps/aws works without prefix.

Versioning Workflow in KV v2

Leverage versioning for history, rollback, undelete, and destruction:

1. Write v1

   vault kv put cloud/apps/aws user=admin password=123 api=XYZ
   

2. Update → v2

   vault kv put cloud/apps/aws user=admin password=456 api=ABC
   

3. Delete latest

   vault kv delete cloud/apps/aws
   

4. Undelete v2 → creates v3

   vault kv undelete cloud/apps/aws --versions=2
   

5. Destroy v3

   vault kv destroy cloud/apps/aws --versions=3
   

6. New write → v4

Next Steps

• Practice writing, reading, updating, and deleting KV secrets
• Explore versioning and metadata queries
• Define Vault policies to secure KV paths

Links and References

• Vault KV Secrets Engine Documentation
• HashiCorp Vault Overview
• Terraform Registry
• Jenkins Plugins
• GitLab CI/CD Docs