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 vault
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.
Launch Terminal
This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.
»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.
Use the vault kv <subcommand> [options]
[args] command to interact with
K/V secrets engine.
Available subcommands:
| 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 | |
| get | x | x | Retrieve data |
| 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.
»Get command help
You can interact with key/value secrets engine using the vault kv command. Get
the command help.
»Write a secret
Before you begin, check the command help.
The help provides command examples along with optional parameters that you can use.
Now, write a key-value secret to the path hello , with a key of foo and value of world, using
the vault kv put command against the mount path secret, which is where the KV v2 secrets engine is mounted. This command creates a new version of the secrets
and replaces any pre-existing data at the path if any.
You will learn about paths in more detail later, but for now it is important that the
mount path to the KV v2 secrets engine is provided with -mount=secret, otherwise this example won't work. The
secret mount path (which was automatically set up for you when you started your Vault server in -dev mode) is where arbitrary secrets can be read and written.
A flag provided but not defined: -mount error means you are using an older version of Vault from before this syntax was introduced.
Upgrade to at least Vault 1.11, or use the old syntax (secret/hello instead of -mount=secret hello) for any commands in this guide.
With kv put you can even write multiple pieces of data.
Notice that the version is now 2.
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
Engine
tutorial to learn different approaches.
»Read a secret
As you might expect, secrets can be retrieved with vault kv get.
Vault returns the latest version (in this case version 2) of the secrets at
secret/hello.
To print only the value of a given field, use the -field=<key_name> flag.
Optional JSON output is very useful for scripts. For example, you can use the
jq tool to extract the value of the excited secret.
»Delete 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.
Try to read the secret you just deleted.
The output only displays the metadata with deletion_time. It does not display
the data itself once it is deleted. Notice that the destroyed parameter is
false which means that you can recover the deleted data if the deletion was
unintentional.
Now, the data is recovered.
NOTE: This quick start tutorial only touches the surface of the key/value v2 secrets engine capabilities. To learn more, go through the Versioned Key/Value Secrets Engine tutorial which will walk you through the key/value v2 secrets engine in greater depth.
»Next
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 engines.
You may notice other tutorials on our site using the kv CLI commands with
a different syntax ($ vault kv get secret/foo instead of the
$ vault kv get -mount=secret foo that we've shown you here). Either style
will have the same end result, but we recommend the more explicit -mount flag
syntax when working with KV secrets engine v2, as it can avoid confusion later
when you need to refer to the secret by its full path (secret/data/foo) when
writing policies or raw API calls.
»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:
