Demo KeyValue KV Version 2 Secrets Engine

In this guide, we’ll walk through using the HashiCorp Vault Key/Value Version 2 (KV v2) Secrets Engine. You’ll learn how to:

• Upgrade an existing KV v1 mount to KV v2
• Enable a new KV v2 mount
• Write, read, and manage versioned secrets
• Delete, undelete, and destroy secret versions
• View and configure metadata (including custom metadata)
• Define policies for KV v2 (data/ and metadata/ prefixes)
• Interact with the Vault HTTP API for KV v2

1. List Existing Secrets Engines

First, verify which secrets engines are currently enabled:

$ vault secrets list
Path         Type      Accessor             Description
----         ----      --------             -----------
cubbyhole/   cubbyhole cubbyhole_9c6c2ca2   per-token private secret storage
identity/    identity  identity_e55fbf01     identity store
sys/         system    system_ae43616e       system endpoints for control, policy, and debugging
training/    kv        kv_1131683            n/a
transit/     transit   transit_5b3af5e       n/a

Here, training/ is mounted as KV v1. Let’s upgrade it to KV v2.

2. Upgrade an Existing KV v1 Mount to KV v2

2.1 Check Mount Details

$ vault secrets list --detailed
Path       Plugin  Accessor      Default TTL  Max TTL  Options  Description
----       ------  --------      -----------  -------  -------  -----------
training/  kv      kv_1d131683   n/a          n/a      map[]    n/a

The training/ mount shows kv_1d131683, indicating version 1.

2.2 Enable Versioning on the Mount

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

Verify that versioning is now enabled:

$ vault secrets list --detailed
Path       Plugin  Accessor      Options        Description
----       ------  --------      -------        -----------
training/  kv      kv_1d131683   map[version:2] n/a

3. Enable a New KV v2 Mount

To start fresh with a KV v2 mount (for example, at kvv2/):

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

Confirm the new mount:

$ vault secrets list
Path       Type    Accessor       Description
----       ----    --------       -----------
kvv2/      kv      kv_0559442e    n/a

4. Write and Read Versioned Secrets

4.1 Write a Secret

Create an initial secret for a CircleCI application:

$ vault kv put kvv2/apps/circleci admin=password

The CLI hides the internal data/ prefix. You should see:

=== Metadata ===
Key              Value
---              -----
created_time     2022-03-25T14:18:15.817666Z
custom_metadata  <nil>
deletion_time    n/a
destroyed        false
version          1

4.2 Update the Secret

Rotate to a stronger password:

$ vault kv put kvv2/apps/circleci admin=P@ssw0rd!

A new version (version 2) is created.

4.3 Read the Latest Version

$ vault kv get kvv2/apps/circleci
==== Secret Path ====
kvv2/data/apps/circleci

==== Metadata ====
Key           Value
---           -----
created_time  2022-03-25T14:19:38.741912Z
version       2

==== Data ====
Key    Value
---    -----
admin  P@ssw0rd!

4.4 Read a Specific Version

$ vault kv get -version=1 kvv2/apps/circleci

This returns the original (version 1) data:

admin   password

5. Delete, Undelete, and Destroy Versions

5.1 Delete the Latest Version

$ vault kv delete kvv2/apps/circleci
Success! Data deleted (if it existed) at: kvv2/apps/circleci

A subsequent vault kv get kvv2/apps/circleci shows metadata only—no data—since version 2 is marked deleted.

5.2 Undelete a Version

$ vault kv undelete --versions=2 kvv2/apps/circleci
Success! Data written to: kvv2/undelete/apps/circleci

Now the data is restored:

$ vault kv get kvv2/apps/circleci
==== Data ====
Key    Value
---    -----
admin  P@ssw0rd!

5.3 Destroy a Version Permanently

$ vault kv destroy --versions=1 kvv2/apps/circleci
Success! Data destroyed for version(s): [1]

Now version 1 is permanently gone (destroyed = true).

6. View and Tune Metadata

6.1 Show Metadata for a Path

$ vault kv metadata get kvv2/apps/circleci

Returns both engine settings and per-version status:

cas_required         false
created_time         2022-03-25T14:19:38.741912Z
current_version      2
delete_version_after 0s
max_versions         0
oldest_version       0
updated_time         2022-03-25T14:19:38.741912Z

Version 1: destroyed = true
Version 2: destroyed = false

6.2 Set Custom Metadata

$ vault kv metadata put -custom-metadata=env=prod,team=devops kvv2/apps/circleci
Success! Data written to: kvv2/metadata/apps/circleci

Verify in the secret output:

$ vault kv get kvv2/apps/circleci
==== Metadata ====
Key              Value
---              -----
custom_metadata  map[env:prod team:devops]

Query Metadata via JSON & jq

$ vault kv get -format=json kvv2/apps/circleci \
    | jq -r '.data.metadata.custom_metadata.env'
prod

7. Fully Delete a Secret Path

To remove all versions and metadata:

$ vault kv metadata delete kvv2/apps/circleci
Success! Data deleted (if it existed) at: kvv2/metadata/apps/circleci

After this, both vault kv list kvv2/apps and vault kv get kvv2/apps/circleci return nothing.

8. Vault UI: Create and Manage Secrets

Use the Vault UI for an interactive experience:

Note

In the Vault UI, navigate to the kvv2 engine, click Create secret, specify the path apps/artifactory, enter your key/value pairs, and save.

After saving, you can view version history, metadata, delete or copy the secret, or create new versions:

9. Writing Policies for KV v2

Policies must reference the data/ and metadata/ prefixes explicitly:

path "kvv2/data/apps/artifactory" {
  capabilities = ["read"]
}

path "kvv2/metadata/apps/artifactory" {
  capabilities = ["read", "list"]
}

Requests without the correct prefix will be denied.

10. Calling the HTTP API

When using curl, include /v1/<mount>/data/… and set your token in the header:

export VAULT_TOKEN="s.yourRootToken"
curl --header "X-Vault-Token: $VAULT_TOKEN" \
     http://127.0.0.1:8200/v1/kvv2/data/apps/artifactory | jq

A sample JSON response:

{
  "data": {
    "data": {
      "artifact": "jenkins"
    },
    "metadata": {
      "version": 1,
      "custom_metadata": null,
      "created_time": "2022-03-25T14:33:10Z"
    }
  }
}

Conclusion

By now you should be familiar with:

• Upgrading KV v1 to KV v2
• Mounting and using new KV v2 engines
• Writing, reading, deleting, undeleting, and destroying versioned secrets
• Viewing and tuning metadata (including custom metadata)
• Defining policies that use the data/ and metadata/ prefixes
• Interacting with the KV v2 HTTP API

Explore these features in your Vault environment to build secure, versioned secret workflows.

Links and References

• HashiCorp Vault Documentation
• Vault KV Version 2 API
• HashiCorp Vault GitHub