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/
.
Command | KV v1 endpoint | KV v2 endpoint |
---|---|---|
vault kv get | secret/<key_path> | secret/data/<key_path> |
vault kv put | secret/<key_path> | secret/data/<key_path> |
vault kv list | secret/<key_path> | secret/metadata/<key_path> |
vault kv delete | secret/<key_path> | secret/data/<key_path> |
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 | KV v2 endpoint |
---|---|
vault kv patch | secret/data/<key_path> |
vault kv rollback | secret/data/<key_path> |
vault kv undelete | secret/undelete/<key_path> |
vault kv destroy | secret/destroy/<key_path> |
vault kv metadata | secret/metadata/<key_path> |
Command examples
Enable KV v1 secrets engine at kv-v1/
.
Enable KV v2 secrets engine at kv-21/
.
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
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.
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.
The following command is equivalent to vault kv put kv-v2/credentials
.
The output tells you that the data was successfully written at
kv-v2/data/credentials
.
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
.
You can check your token's capabilities at the path.
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.
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?
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.