Compare Key/Value Secrets Engine v1 and v2

The Static Secrets: Key/Value Secrets Engine tutorial introduced the basics of working with KV secrets engine v1. The Versioned Key/Value Secrets Engine tutorial walked through KV secrets engine v2 features.

This tutorial compares the two versions of KV secrets engine.

API endpoint comparison

Regardless of its version, you can ues the vault kv command to interact with K/V secrets engine. However, the actual API endpoint that the CLI command invokes are slightly different beteween KV v1 and KV v2.

The following table lists the vault kv subcommands and their respecting API endpoint. This assumes that the KV secrets engine is enabled at secret/.

This throws off some users when they are writing policies.

In addition, KV v2 has additional subcommands that are not available for KV v1.

Command examples

Enable KV v1 secrets engine at kv-v1/.

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

Enable KV v2 secrets engine at kv-21/.

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

You can use -output-curl-string command to print an equivalent cURL command string for any vault command. Run the vault kv command with the -output-curl-string flag against KV v1 and v2.

Key/Value v1

$ vault kv get -output-curl-string kv-v1/test
curl -H "X-Vault-Request: true" -H "X-Vault-Token: $(vault print token)" http://127.0.0.1:8200/v1/kv-v1/test

The endpoint is /kv-v1/test which matches the command.

Key/Value v2

Now, run the same command against kv-v2 to compare the output.

$ vault kv get -output-curl-string kv-v2/test 
curl -H "X-Vault-Request: true" -H "X-Vault-Token: $(vault print token)" http://127.0.0.1:8200/v1/kv-v2/data/test

The endpoint is /kv-v2/data/test although the CLI command queried for kv-v2/test. The Vault CLI is a convenient wrapper around the API. Based on the target secrets engine, it sends requests to the appropriate API endpoint.

This behavior was confusing. To reduce this confusion, Vault 1.11.0 introduced the -mount flag to change the way you interact with the KV secrets engine. You specify where the target secrets engine is enabled at (<mount_path>) and the secret key (key) you wish to access.

$ vault kv get -mount=<mount_path> <key>

The following command is equivalent to vault kv put kv-v2/credentials.

$ vault kv put -mount="kv-v2" credentials user_name="student01" password="weior3892nenq"

The output tells you that the data was successfully written at kv-v2/data/credentials.

===== Secret Path =====
kv-v2/data/credentials

======= Metadata =======
Key                Value
---                -----
created_time       2022-06-17T05:33:39.375905Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Troubleshoot ACL policies

The easiest way to figure out the policy you must have to perform a specific Vault operation, use the -output-policy flag. (NOTE: The -output-policy flag requires Vault 1.11.0 or later.)

For example, you received a permission denied error when you tried to list secrets at kv-v2/customers.

$ vault kv list kv-v2/customers
Error listing kv-v2/metadata/customers: Error making API request.

URL: GET http://127.0.0.1:8200/v1/kv-v2/metadata/customers?list=true
Code: 403. Errors:

* 1 error occurred:
    * permission denied

You can check your token's capabilities at the path.

$ vault token capabilities kv-v2/data/customers
create, delete, list, read

You may think the list capability should allow the operation.

To find out the policy required to perform the vault kv list kv-v2/customers command, you can use the -output-policy flag.

$ vault kv list -output-policy kv-v2/customers
path "kv-v2/metadata/customers" {
  capabilities = ["read"]
}

To list all secrets under kv-v2/data/customers, you need the read capability on the kv-v2/metadata/customers path.

What about the KV v1 secrets engine?

$ vault kv list -output-policy kv-v1/customers
path "kv-v1/customers" {
  capabilities = ["read"]
}

The -output-policy flag helps you to write ACL policies necessary to perform operations required by each Vault client.

If you are not familiar with policies, complete the policies tutorial.

Help and reference

• Key/Value Secrets Engine
• Key/Value Secrets Engine API