KV secrets engine

The kv secrets engine is a generic Key-Value store used to store arbitrary secrets within the configured physical storage for Vault. This secrets engine can run in one of two modes; store a single value for a key, or store a number of versions for each key and maintain the record of them.

KV version 1

When running the kv secrets engine non-versioned, it stores the most recently written value for a key. Any update will overwrite the original value and not recoverable. The benefits of non-versioned kv is a reduced storage size for each key since no additional metadata or history is stored. Additionally, it gives better runtime performance because the requests require fewer storage calls and no locking.

Refer to the KV version 1 Docs for more information.

KV version 2

When running v2 of the kv secrets engine, a key can retain a configurable number of versions. The default is 10 versions. The older versions' metadata and data can be retrieved. Additionally, it provides check-and-set operations to prevent overwriting data unintentionally.

When a version is deleted, the underlying data is not removed, rather it is marked as deleted. Deleted versions can be undeleted. To permanently remove a version's data, use the vault kv destroy command or the API endpoint. You can delete all versions and metadata for a key by deleting the metadata using the vault kv metadata delete command or the API endpoint with DELETE verb. You can restrict who has permissions to soft delete, undelete, or fully remove data with Vault policies.

Refer to the KV version 2 Docs for more information.

Version comparison

Regardless of its version, you use the vault kv command to interact with KV secrets engine. However, the API endpoint are different. You must be aware of those differences to write policies as intended.

The following table lists the vault kv sub-commands and their respective API endpoints assuming the KV secrets engine is enabled at secret/.

In addition, KV v2 has sub-commands to handle versioning of secrets.

To reduce confusion, the CLI command outputs the secret path when you are working with KV v2.

Example:

$ vault kv put secret/web-app api-token="WEOIRJ13895130WENJWEFN"

=== Secret Path ===
secret/data/web-app

======= Metadata =======
Key                Value
---                -----
created_time       2024-07-02T00:34:58.074825Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

You can use -mount flag if omitting /data/ in the CLI command is confusing.

$ vault kv put -mount=secret web-app api-token="WEOIRJ13895130WENJWEFN"