KeyValue Secrets Engine

Now that we understand what Secrets Engines are and how they’re used in Vault, this lesson dives into the Key/Value (KV) Secrets Engine — Vault’s primary store for static secrets. The KV Secrets Engine stores static secrets: items created outside of Vault that you want to store securely for applications or users to retrieve (for example, certificates, usernames/passwords, or API keys). If secrets are not generated dynamically by Vault, the KV store is usually the right place to put them. Key concepts at a glance:

KV v2 is a versioned key-value store that retains previous secret versions.
KV v1 is a non-versioned key-value store where updates overwrite previous values.
KV secrets are accessible via the Vault UI, CLI, and API.
Access is controlled by Vault policies scoped to mount paths and nested paths.
All KV data is encrypted before being persisted (AES-256).

Use cases: static credentials, certificates, API tokens, secrets consumed by automation (CI/CD, configuration management) and applications.

KV versions: v1 vs v2

Feature	KV v1	KV v2
Versioning	No — writes overwrite existing data	Yes — each update creates a new version and retains history
Metadata	No	Yes — creation time, deletion time, destroyed flag, custom user metadata
API prefixes	N/A	Requires `data/` and `metadata/` prefixes for API calls
CLI behavior	Direct paths (e.g., `vault kv get kv/path`)	CLI hides `data/`/`metadata/` prefixes for you
Use when	You want simple, non-versioned storage	You need history, auditability, or soft-delete/undelete behavior

Access to KV secrets is available through all three Vault interfaces: the UI, the CLI, and the API. That makes KV useful for both interactive use and automation (Terraform, Jenkins, GitLab CI/CD, etc.). Design your KV layout before bulk-writing secrets — choose a single large mount with organized paths, or multiple mounts (for example, one per team) to simplify policy boundaries.

A presentation slide showing a "Key/Value Secrets Engine" diagram with a central kv/ vault icon linked to three orange nodes labeled cloud, automation, and data. Each node branches into smaller service and environment labels (e.g., aws, chef, jenkins, dev, prod) to illustrate organization of secrets.

Organization and storage model

Secrets are stored as key-value pairs at specific paths under an engine’s mount path. Example layout ideas:

Mount a KV engine at apps/.
- Store secrets for a web app at apps/aws/prod/.
- Under that path you can keep multiple keys (username, password, API key, certificate, etc.).
Or, have multiple mounts (e.g., cloud/, automation/, data/) to isolate teams and simplify policies.

Common organization patterns:

Single mount with hierarchical paths: kv/cloud/aws/prod, kv/automation/dev.
Multiple mounts: cloud/ (KV), automation/ (KV), data/ (KV).

Each mount is isolated and governed by policies attached to that mount path.

A presentation slide titled "Key/Value Secrets Engine" that explains organizing data across multiple KV stores. The diagram shows icons for cloud, data, and automation connected to hierarchical nodes like aws, chef, dev, prod, jenkins, and apps.

Example paths and stored data

If a KV engine is mounted at apps/, example paths might be:

apps/aws/prod contains:
- user = dbadmin
- password = P@ssw0rd
- api = b93md83mdmapw
apps/aws/dev contains:
- cert = ---BEGIN CERTIFICATE...
- key = ---BEGIN PRIVATE KEY...

A read against apps/aws/prod returns the key-value pairs stored at that path. Example representation:

# apps/aws/prod
user=dbadmin
password=P@ssw0rd
api=b93md83mdmapw

# apps/aws/dev
cert=---BEGIN CERTIFICATE...
key=---BEGIN PRIVATE KEY...

Capabilities required to write

Operation	Vault capability required
Create a new secret path	`create` capability on the target path
Overwrite or update existing secret	`update` capability on the target path
Read secret	`read` capability
Delete/Destroy	`delete` or `destroy` as applicable (v2 specific)

When running Vault in development mode (vault server -dev), Vault automatically enables a KV v2 secrets engine mounted at secret/. In production, you must explicitly enable KV engines where needed.

Enabling the KV Secrets Engine

Enable on any mount path (except protected paths like sys or auth). You can enable multiple KV engines on different mount paths; each acts independently and is governed by policies. Enabling via the UI:

In the Vault UI: go to Secrets → Enable new secrets engine → choose “Key/Value” → pick mount path → select KV v1 or v2 and configure options (description, max versions, CAS, etc.).

Enable via the CLI (examples) Enable a KV engine at the default mount kv/:

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

Enable a KV engine at a custom mount training/:

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

List secrets engines (detailed output):

$ vault secrets list -detailed
Path        Plugin      Accessor         Options
----        ------      --------         -------
cubbyhole/  cubbyhole   cubbyhole_ee5ae49  map[]
kv/         kv          kv_e8b99a3         map[]
training/   kv          kv_1d5e9cc1        map[]

An empty map[] in Options indicates a KV v1 engine. For KV v2, the Options map contains "version": "2" (or similar).

Enabling and upgrading to KV v2

To enable a mount as KV v2, configure it when enabling or tune an existing mount. To upgrade from KV v1 to KV v2:

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

Upgrading a KV v1 mount to KV v2 is irreversible. You cannot downgrade from v2 back to v1 once versioning is enabled. Plan carefully and ensure your policies and automation accommodate the change.

How KV v2 is different KV v2 stores per-version metadata along with secret data. Metadata includes creation time, version number, deletion time, and a “destroyed” state. Because of this separation, KV v2 introduces two API prefixes:

.../data/... — where secret data is stored and read from via the API.
.../metadata/... — where metadata operations (list, read metadata, etc.) operate.

Example: a KV v2 engine mounted at cloud/

Data for apps/aws/network is available via API at cloud/data/apps/aws/network.
Metadata is accessible at cloud/metadata/apps/aws/network.

The Vault CLI hides the data/ and metadata/ prefixes for you. When using the CLI you can run vault kv get cloud/apps/aws/network without adding the data/ prefix. When working with the API or writing policies for KV v2, you must use data/ and metadata/ prefixes explicitly.

KV v2 versioning behavior (common operations)

Versioning gives fine-grained control over secret history and lifecycle.

Operation	Effect
Create (first write)	Writes version 1
Update	Creates a new version (increments version number)
Read	Returns latest non-deleted version by default
Delete (soft delete)	Marks versions as deleted (data still retained in metadata)
Undelete	Clears soft-delete markers for specific versions; does not create a new version
Rollback	Rewriting a previous version’s data creates a new version (rollback results in a new version)
Destroy	Permanently removes a specific version’s data; irreversible except via backup restore

Concise conceptual workflow:

Write initial version (v1)

pass=123
api=3jd93kd
user=admin
# -> version 1

Update (creates v2)

pass=456
api=mfid02s
user=admin
# -> version 2 (v1 retained)

Delete latest (soft delete of v2)

Reading returns no secret data (metadata remains).
You can undelete v2 to restore it.

Rollback to v1

Writing v1’s data again creates v3 (new version) containing the v1 contents.

Destroy a version (permanent)

destroy permanently removes the specified version data.

Because KV v2 supports soft deletes, metadata inspection, and explicit destroys, it provides robust lifecycle controls for secret retention and recovery.

Best practices

Design your KV structure before bulk writing secrets — consistency reduces policy complexity.
Use multiple mounts for team isolation when teams must not share policies or access paths.
Use KV v2 when you need version history, soft-deletes, and auditability.
When writing policies for KV v2, reference data/ and metadata/ paths explicitly.
For automation, prefer the CLI or API and ensure the service account has minimal required capabilities (create, read, update, delete, etc.).

References and further reading

HashiCorp Vault Documentation — Key/Value Secrets Engine: https://www.vaultproject.io/docs/secrets/kv
Vault CLI reference: https://www.vaultproject.io/docs/commands
Vault Policies: https://www.vaultproject.io/docs/concepts/policies

Summary and next steps KV Secrets Engines are the canonical place to store static secrets in Vault. Decide on an organizational model (single mount vs multiple mounts), enable the KV mounts you need (v1 or v2), and write policies granting the required capabilities on the correct paths. When using KV v2, remember to account for the data/ and metadata/ prefixes in API calls and policies. We’ll move on to hands-on examples showing CLI and API operations against both KV v1 and KV v2.

Introduction

Introduction to Vault

Learning the Vault Architecture

Installing Vault

Compare Authentication Methods

Create Vault Policies

Assess Vault Tokens

Compare and Configure Secrets Engines

Vault Agent

Vault Replication

KeyValue Secrets Engine

KV versions: v1 vs v2

Organization and storage model

Example paths and stored data

Capabilities required to write

Enabling the KV Secrets Engine

Enabling and upgrading to KV v2

KV v2 versioning behavior (common operations)

Best practices

References and further reading

Watch Video

​KV versions: v1 vs v2

​Organization and storage model

​Example paths and stored data

​Capabilities required to write

​Enabling the KV Secrets Engine

​Enabling and upgrading to KV v2

​KV v2 versioning behavior (common operations)

​Best practices

​References and further reading

Watch Video

KV versions: v1 vs v2

Organization and storage model

Example paths and stored data

Capabilities required to write

Enabling the KV Secrets Engine

Enabling and upgrading to KV v2

KV v2 versioning behavior (common operations)

Best practices

References and further reading