Skip to main content
In this guide, we’ll explore the Key/Value (KV) Secrets Engine in Vault, focusing on what Operations Professionals need to know. The KV Secrets Engine is ideal for storing static secrets—such as service-account passwords or API keys—that are generated outside Vault. While Vault also offers powerful dynamic credentials, static secrets remain ubiquitous in many environments. Vault supports two flavors of the KV Secrets Engine:
  • Version 1: A simple, non-versioned store.
  • Version 2: A fully versioned store, tracking metadata (creation time, version number, deletion status, etc.).
Secrets can be accessed via the UI, CLI, or API. Access control is enforced by Vault policies that grant specific capabilities (create, read, update, delete) on defined paths. All data at rest is encrypted using AES-256. You can mount multiple KV engines at unique paths to isolate workloads.
The image is a slide about the Key/Value Secrets Engine, explaining how it can be enabled at different paths, stores secrets as key-value pairs, and requires specific capabilities for writing and updating secrets.

​
How to Store Secrets as Key/Value Pairs

To write secrets, choose a mount path and supply your key/value pairs. For example, after enabling the KV engine at secret/: 
vault write secret/applications/web01 \
  user=dbadmin \
  password=P@ssw0rd \
  api=b93md83mdmapw
  • create capability is required when writing to a new path.
  • update capability is required for overwriting an existing secret.
Ensure your Vault policies explicitly grant create and update permissions on the exact path (e.g., secret/applications/web01) or via wildcards (e.g., secret/applications/*).

​
Organizing a KV Engine Hierarchy

Suppose you mount a KV engine at apps/. You can structure environments like this:
  • apps/AWS/prod – Production credentials
  • apps/AWS/dev – Development certificates
Example writes: 
vault write apps/AWS/prod \
  user=dbadmin \
  password=P@ssw0rd \
  api=b93md83mdmapw

vault write apps/AWS/dev \
  cert='---BEGIN CERTI...' \
  key='---BEGIN PRIVA...'
You can also manage KV engines via the CLI.

​
Enabling and Listing KV Version 1

# Enable a KV v1 engine at the default path kv/
vault secrets enable kv

# Enable a KV v1 engine at a custom path hcvop/
vault secrets enable -path=hcvop kv

# List all secrets engines with detailed info
vault secrets list --detailed
PathPluginAccessorOptions
cubbyhole/cubbyholecubbyhole_*map[]
kv/kvkv_*map[]
hcvop/kvkv_*map[]
An empty map[] under Options indicates a KV v1 store.

​
Enabling and Listing KV Version 2

You can enable KV v2 with either shorthand or an explicit version flag. Method 1 (shorthand): 
vault secrets enable kv-v2
Method 2 (explicit): 
vault secrets enable -path=training -version=2 kv
Re-run the listing: 
vault secrets list --detailed
PathPluginAccessorOptions
cubbyhole/cubbyholecubbyhole_*map[]
kv-v2/kvkv_*map[version:2]
training/kvkv_*map[version:2]
The map[version:2] entry marks a KV v2 store.

​
Upgrading a KV v1 Engine to v2

You can convert an existing KV v1 mount to version 2. Be aware this action is irreversible without restoring from backup.
Upgrading to KV v2 cannot be undone. Ensure you have a backup of your Vault data before proceeding.
vault kv enable-versioning training/
# Success! Tuned the secrets engine at: training/

​
Understanding KV v2 Metadata and Path Prefixes

KV v2 tracks detailed metadata (creation date, version, deletion status, custom fields) for every secret. To support versioning, KV v2 introduces two API path prefixes:
  • data/ – Stores the secret data
  • metadata/ – Stores the versioning metadata
The image explains how KV V2 is different by adding metadata to key-value entries for versioning, introducing two prefixes: "cloud/data" for storing actual data and "cloud/metadata" for storing metadata about a secret. It also features a Vault certification badge and a cartoon character.
For a KV v2 engine mounted at cloud/ with a secret path apps/AWS/network:
  • Data path: cloud/data/apps/AWS/network
  • Metadata path: cloud/metadata/apps/AWS/network
The image explains the structure of KV V2, showing a hierarchy of paths for storing secrets in a cloud environment, with a specific path format and a "data/" prefix for reading secrets. It also features a Vault certification badge and a cartoon character.
When working with the API or writing policies, you must include the data/ and metadata/ prefixes. The vault kv CLI commands automatically handle these prefixes for you:
The image provides information about KV V2, highlighting that the data/ and metadata/ prefixes are required for API and Vault policies, but it does not change CLI interactions. It also features a Vault certification badge and a cartoon character.

​
Next Steps

You’re now ready to get hands-on with KV v1 and KV v2 in Vault. Practice writing policies, making API calls, and exploring the versioning features to master static secret management.

Watch Video