KV Secrets Engine (Version 1 & 2)

The KV Secrets Engine — short for Key-Value Secrets Engine — is a built-in storage backend within Vault that lets you store and retrieve arbitrary secrets as simple key-value pairs. A 'key' is like a label (for example, 'api-key'), and a 'value' is the actual secret data (for example, 'abc123xyz'). This is the simplest way to get secrets into Vault, and it does not require any external database or cloud service.

Vault offers two versions of this engine: Version 1 (sometimes called KV v1) and Version 2 (KV v2). They both store data in the same basic key-value format, but they behave very differently when you read, write, or delete secrets.

On Version 1, there is no versioning. When you write a secret to a path — a path is like a folder location in a filesystem, for example 'secret/myapp/database' — Vault simply overwrites whatever was there before. If you read the secret back, you get only the most recent value. If you delete the secret, it is gone forever. There is no undo, no history, no recovery. This is fine for static secrets that rarely change and where old values have no value. However, if a developer accidentally overwrites a production database password, you cannot roll it back. This lack of safety is the biggest limitation of Version 1.

Version 2 introduces full secret versioning. Think of it like Git for secrets. Every time you write a new value to the same path, Vault increments the version number and keeps the previous version intact. By default, Vault stores the ten most recent versions, but you can configure this 'max-versions' parameter to any number you like — including unlimited, though that consumes more storage. When you read a path in KV v2, you always get the latest version unless you explicitly request an older one by appending '?version=1' to your read request.

Version 2 also adds soft delete capabilities. With soft delete, you can delete a secret but not permanently erase it. Instead, the secret is marked as deleted and hidden from normal listing operations. It remains in storage for a configurable period — typically 30 days — after which a 'destroy' operation permanently removes it. This mimics a recycle bin: if you accidentally delete a production certificate, you can undelete it as long as the grace period has not expired.

Another important feature is the 'delete-version' operation in v2. You can delete a specific version number — for example, delete version 3 of a secret while keeping versions 1, 2, and 4. This is useful if a secret was compromised and you need to remove only the leaked version from history, while keeping others for auditing.

The choice between versions depends on your use case:

Both versions support listing all secrets under a path (like 'ls' on a directory) and reading individual secrets. However, they use different API endpoints internally. A Vault administrator enables the engine on a mount path — typically 'secret/' — and specifies the version parameter: either 1 or 2. Once enabled, the version is fixed for that mount path; you cannot change it later without migrating data manually.

In summary, the KV secrets engine solves the problem of storing static secrets — secrets that do not automatically rotate — in a central, secure location. It replaces scattered configuration files, environment variables, and hard-coded passwords that are difficult to manage and audit. The version 2 improvements add the safety net of history and recovery, which is why most production Vault deployments use KV v2 despite its slightly higher storage overhead.

Imagine you are the sole IT administrator for 'GreenLeaf Tech', a small software company that builds a customer relationship management (CRM) application. The CRM needs to connect to a PostgreSQL database, an external payment API, and an SMTP email server. Currently, the database password is stored in a plain text file on a shared network drive. The payment API key is hard-coded in the application source code. This is a security nightmare: any employee who accesses the shared drive can read the database password, and the API key is exposed in the Git repository history.

You decide to implement HashiCorp Vault to centralise and secure these secrets. For your first deployment, you choose the KV secrets engine because all three secrets are static — they do not change automatically, and you manage them manually.

Here is the step-by-step process you follow:

Three months later, a security audit reveals that the payment API key has been compromised. You need to rotate the key immediately. You generate a new key from the payment provider and write it to the same path: vault kv put secret/crm/payment api_key=pk_live_YYYYYYYYYYYYYYYYYYYY. Vault stores this as version 2. The audit log shows that you overwrote the secret at 2:15 PM on Tuesday.

During the rotation, a junior developer accidentally writes the old compromised key back to the path, thinking they are restoring the 'correct' value. This creates version 3 — which is actually the compromised key again. You detect this error within hours. Because you are using KV v2, you can run: vault kv rollback secret/crm/payment 2. This command restores version 2 as the latest version, effectively undoing the developer's mistake. The compromised version 3 still exists in the history, but it is no longer the active secret.

Later, you decide to decommission the old SMTP server. You soft delete its credentials: vault kv metadata delete secret/crm/smtp. The secret disappears from normal listings, but it remains recoverable for 30 days in case another service still references it. After 30 days, a periodic cleanup job runs vault kv destroy secret/crm/smtp, which permanently removes the data.

As the company grows, you configure the maximum versions to 20 for the CRM path, ensuring you always have enough history for auditing but not wasting storage on infinite old versions. You also enable soft delete with a 60-day undelete period for all critical secrets.

This real-world scenario shows how KV v2 gives you operational safety without sacrificing simplicity. The VA-003 exam will expect you to recognise exactly this kind of workflow: when to use put, get, delete, destroy, and rollback, and which version supports each operation.