KV secrets engine - version 1

[!IMPORTANT]
Documentation Update: Product documentation, which were located in this repository under /website, are now located in hashicorp/web-unified-docs, colocated with all other product documentation. Contributions to this content should be done in the web-unified-docs repo, and not this one. Changes made to /website content in this repo will not be reflected on the developer.hashicorp.com website.

The kv secrets engine is used to store arbitrary secrets within the configured physical storage for Vault.

Writing to a key in the kv backend will replace the old value; sub-fields are not merged together.

Key names must always be strings. If you write non-string values directly via the CLI, they will be converted into strings. However, you can preserve non-string values by writing the key/value pairs to Vault from a JSON file or using the HTTP API.

This secrets engine honors the distinction between the create and update capabilities inside ACL policies.

Setup

To enable a version 1 kv store:

$ vault secrets enable -version=1 kv

Usage

After the secrets engine is configured and a user/machine has a Vault token with the proper permission, it can generate credentials. The kv secrets engine allows for writing keys with arbitrary values.

1. Write arbitrary data:

   $ vault kv put kv/my-secret my-value=s3cr3t
   Success! Data written to: kv/my-secret
   

2. Read arbitrary data:

   $ vault kv get kv/my-secret
   Key                 Value
   ---                 -----
   my-value            s3cr3t
   

3. List the keys:

   $ vault kv list kv/
   Keys
   ----
   my-secret
   

4. Delete a key:

   $ vault kv delete kv/my-secret
   Success! Data deleted (if it existed) at: kv/my-secret
   

You can also use Vault's password policy feature to generate arbitrary values.

1. Write a password policy:

   $ vault write sys/policies/password/example policy=-<<EOF
   
     length=20
   
     rule "charset" {
       charset = "abcdefghij0123456789"
       min-chars = 1
     }
   
     rule "charset" {
       charset = "!@#$%^&*STUVWXYZ"
       min-chars = 1
     }
   
   EOF
   

2. Write data using the example policy:

   $ vault kv put kv/my-generated-secret \
       password=$(vault read -field password sys/policies/password/example/generate)
   

3. Read the generated data:

   $ vault kv get kv/my-generated-secret
   ====== Data ======
   Key         Value
   ---         -----
   password    ^dajd609Xf8Zhac$dW24
   

TTLs

Unlike other secrets engines, the KV secrets engine does not enforce TTLs for expiration. Instead, the lease_duration is a hint for how often consumers should check back for a new value.

If provided a key of ttl, the KV secrets engine will utilize this value as the lease duration:

$ vault kv put kv/my-secret ttl=30m my-value=s3cr3t
Success! Data written to: kv/my-secret

Even with a ttl set, the secrets engine never removes data on its own. The ttl key is merely advisory.

When reading a value with a ttl, both the ttl key and the refresh interval will reflect the value:

$ vault kv get kv/my-secret
Key                 Value
---                 -----
my-value            s3cr3t
ttl                 30m

API

The KV secrets engine has a full HTTP API. Please see the KV secrets engine API for more details.