If you successfully completed the steps in Starting the
Server, you started the dev server
and exported the
VAULT_TOKEN to the initial root token value so that
login is not required to authenticate. If you have not yet completed those
steps, please review that tutorial and do so before proceeding here.
Now that the dev server is up and running, let's get straight to it and read and write your first secret.
NOTE: An interactive tutorial is also available to perform the steps described in this tutorial. Click the Show Terminal button to start.
»Key/Value secrets engine
When running Vault in dev mode, Key/Value v2 secrets
engine is enabled at
secret/ path. Key/Value secrets engine is a generic key-value store used to
store arbitrary secrets within the configured physical storage for Vault.
Secrets written to Vault are encrypted and then written to backend storage.
Therefore, the backend storage mechanism never sees the unencrypted value and
doesn't have the means necessary to decrypt it without Vault.
Key/Value secrets engine has version 1 and 2. The difference is that v2 provides versioning of secrets and v1 does not.
vault kv <subcommand> [options]
[args] command to interact with
K/V secrets engine.
|Subcommand||kv v1||kv v2||Description|
|delete||x||x||Delete versions of secrets stored in K/V|
|destroy||x||Permanently remove one or more versions of secrets|
|enable-versioning||x||Turns on versioning for an existing K/V v1 store|
|list||x||x||List data or secrets|
|metadata||x||Interact with Vault's Key-Value storage|
|patch||x||Update secrets without overwriting existing secrets|
|put||x||x||Sets or update secrets (this replaces existing secrets)|
|rollback||x||Rolls back to a previous version of secrets|
|undelete||x||Restore the deleted version of secrets|
To learn more about Key/Value v1 secrets engine, go through the Static Secrets: Key/Value Secrets Engine tutorial.
»Writing a Secret
Before you begin, check to verify that no secrets exists at
$ vault kv get secret/helloNo value found at secret/data/hello
Now, write a secret
foo with value of
world to the path
vault kv put command. This command creates a new version of the secrets
and replaces any pre-existing data at the path if any.
$ vault kv put secret/hello foo=world Key Value--- -----created_time 2020-09-02T21:40:01.635656Zdeletion_time n/adestroyed falseversion 1
You will learn paths in more detail later, but for now it is important that the
path is prefixed with
secret/, otherwise this example won't work. The
secret/ prefix is where arbitrary secrets can be read and written.
You can even write multiple pieces of data.
$ vault kv put secret/hello foo=world excited=yes Key Value--- -----created_time 2020-09-02T21:41:17.568155Zdeletion_time n/adestroyed falseversion 2
Notice that the
version is now
Warning: The examples in this tutorial use the
<key>=<value> input to
send secrets to Vault. However, sending data as a part of the CLI command often
end up in the shell history unencrypted. To avoid this, refer to the Static
Secrets: Key/Value Secrets
tutorial to learn different approaches.
»Getting a Secret
As you might expect, secrets can be retrieved with
vault kv get <path>.
$ vault kv get secret/hello ====== Metadata ======Key Value--- -----created_time 2020-09-02T21:41:17.568155Zdeletion_time n/adestroyed falseversion 2 ===== Data =====Key Value--- -----excited yesfoo world
Vault returns the latest version (in this case version
2) of the secrets at
To print only the value of a given field, use the
$ vault kv get -field=excited secret/hello yes
Optional JSON output is very useful for scripts. For example, you can use the
jq tool to extract the value of the
$ vault kv get -format=json secret/hello | jq -r .data.data.excited yes
»Deleting a Secret
Now that you've learned how to read and write a secret, let's go ahead
and delete it. You can do so using the
vault kv delete command.
$ vault kv delete secret/hello Success! Data deleted (if it existed) at: secret/hello
In this tutorial, you learned how to use the powerful CRUD features of Vault to store arbitrary secrets. On its own, this is already a useful but basic feature. Key/Value secrets engine is one of the secrets engines that Vault offers.
Continue to the Secrets Engine tutorial for a quick tour of Vault secrets engine.
»Help and reference
This tutorial only touched the basis of the Key/Value secrets engine. To learn more about the features of Key/Value secrets engines, go through the following tutorials: