Key-Value Secrets Engine
You'll learn how HashiCorp Vault's KV secrets engine stores static secrets with two versions (v1 and v2) that offer different levels of versioning and metadata.
What is the Key-Value Secrets Engine?
The Key-Value (KV) secrets engine is Vault's simplest and most commonly used secrets engine for storing arbitrary key-value pairs—think usernames, passwords, API keys, or configuration data. Unlike dynamic secrets engines that generate credentials on-demand, KV stores static secrets you provide.
Think of it like a secure filing cabinet: KV v1 is a single drawer where updating a document destroys the old version, while KV v2 is a multi-drawer system that keeps historical copies of every document you file.
KV Version 1 (v1)
KV v1 provides straightforward storage with no versioning. When you update a secret, the old value is permanently overwritten. It's lightweight and perfect when you don't need audit trails of previous values.
# Enable KV v1 engine
vault secrets enable -path=secret kv
# Write a secret
vault kv put secret/myapp password=oldpass123
# Update overwrites completely
vault kv put secret/myapp password=newpass456
# Reading returns only current value
vault kv get secret/myapp
KV Version 2 (v2)
KV v2 adds automatic versioning, metadata tracking, and soft-delete capabilities. Every write creates a new version, and you can retrieve historical versions or roll back changes. This is critical for compliance and recovery scenarios.
# Enable KV v2 engine
vault secrets enable -version=2 -path=kv kv
# Each write creates a new version
vault kv put kv/myapp password=firstpass
vault kv put kv/myapp password=secondpass
# Read specific version
vault kv get -version=1 kv/myapp
vault kv get -version=2 kv/myapp
# View all versions and metadata
vault kv metadata get kv/myapp
Key Takeaway: Use KV v1 for simple, low-overhead secret storage where history doesn't matter; choose KV v2 when you need versioning, rollback capability, and detailed audit trails for compliance and operational safety.