If you successfully completed the steps in Starting theServer, you started the dev serverand exported the VAULT_TOKEN
to the initial root token value so that vaultlogin
is not required to authenticate. If you have not yet completed thosesteps, 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 andwrite your first secret.
Launch Terminal
This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.
When running Vault in dev mode, Key/Value v2 secretsengine is enabled atsecret/
path. Key/Value secrets engine is a generic key-value store used tostore 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 anddoesn't have the means necessary to decrypt it without Vault.
Key/Value secrets engine has version 1 and 2. The difference is that v2provides versioning of secrets and v1 does not.
Use the vault kv <subcommand> [options][args] command to interact withK/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, review the KV secrets engine - version 1 documentation.
Get command help
You can interact with key/value secrets engine using the vault kv
command. Getthe command help.
$ vault kv -help Usage: vault kv <subcommand> [options] [args] This command has subcommands for interacting with Vault's key-value store. Here are some simple examples, and more detailed examples are available in the subcommands or the documentation. Create or update the key named "foo" in the "secret" mount with the value "bar=baz": $ vault kv put -mount=secret foo bar=baz Read this value back: $ vault kv get -mount=secret foo Get metadata for the key: $ vault kv metadata get -mount=secret foo Get a specific version of the key: $ vault kv get -mount=secret -version=1 foo The deprecated path-like syntax can also be used, but this should be avoided for KV v2, as the fact that it is not actually the full API path to the secret (secret/data/foo) can cause confusion: $ vault kv get secret/foo Please see the individual subcommand help for detailed usage information.Subcommands: delete Deletes versions in the KV store destroy Permanently removes one or more versions in the KV store enable-versioning Turns on versioning for a KV store get Retrieves data from the KV store list List data or secrets metadata Interact with Vault's Key-Value storage patch Sets or updates data in the KV store without overwriting put Sets or updates data in the KV store rollback Rolls back to a previous version of data undelete Undeletes versions in the KV store
Before you begin, check the command help.
$ vault kv put -help
The help provides command examples along with optional parameters that you canuse.
Now, write a key-value secret to the path hello
, with a key of foo
and value of world
, usingthe 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 secretsand replaces any pre-existing data at the path if any.
$ vault kv put -mount=secret hello foo=world== Secret Path ==secret/data/hello======= Metadata =======Key Value--- -----created_time 2022-06-15T19:36:54.389113Zcustom_metadata <nil>deletion_time n/adestroyed falseversion 1
You will learn about paths in more detail later, but for now it is important that themount path to the KV v2 secrets engine is provided with -mount=secret
, otherwise this example won't work. Thesecret
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.
$ vault kv put -mount=secret hello foo=world excited=yes== Secret Path ==secret/data/hello======= Metadata =======Key Value--- -----created_time 2022-06-15T19:49:06.761365Zcustom_metadata <nil>deletion_time n/adestroyed falseversion 2
Notice that the version
is now 2
.
Warning The examples in this tutorial use the <key>=<value>
input tosend secrets to Vault. However, sending data as a part of the CLI command oftenend up in the shell history unencrypted. To avoid this, refer to the Versioned Key/value secrets enginetutorial to learn different approaches.
Read a secret
As you might expect, secrets can be retrieved with vault kv get
.
$ vault kv get -mount=secret hello== Secret Path ==secret/data/hello======= Metadata =======Key Value--- -----created_time 2022-01-15T01:40:09.888293Zcustom_metadata <nil>deletion_time n/adestroyed falseversion 2===== Data =====Key Value--- -----excited yesfoo world
Vault returns the latest version (in this case version 2
) of the secrets atsecret/hello
.
To print only the value of a given field, use the -field=<key_name>
flag.
$ vault kv get -mount=secret -field=excited helloyes
Optional JSON output is very useful for scripts. For example, you can use thejq
tool to extract the value of the excited
secret.
$ vault kv get -mount=secret -format=json hello | jq -r .data.data.excitedyes
Now that you've learned how to read and write a secret, let's go aheadand delete it. You can do so using the vault kv delete
command.
$ vault kv delete -mount=secret helloSuccess! Data deleted (if it existed) at: secret/data/hello
Try to read the secret you just deleted.
$ vault kv get -mount=secret hello== Secret Path ==secret/data/hello======= Metadata =======Key Value--- -----created_time 2022-01-15T01:40:09.888293Zcustom_metadata <nil>deletion_time 2022-01-15T01:40:41.786995Zdestroyed falseversion 2
The output only displays the metadata with deletion_time
. It does not displaythe data itself once it is deleted. Notice that the destroyed
parameter isfalse
which means that you can recover the deleted data if the deletion wasunintentional.
$ vault kv undelete -mount=secret -versions=2 helloSuccess! Data written to: secret/undelete/hello
Now, the data is recovered.
$ vault kv get -mount=secret hello======= Metadata =======Key Value--- -----created_time 2022-01-15T01:40:09.888293Zcustom_metadata <nil>deletion_time n/adestroyed falseversion 2===== Data =====Key Value--- -----excited yesfoo world
Note This quick start tutorial only touches the surface of the key/valuev2 secrets engine capabilities. To learn more, go through the VersionedKey/Value Secrets Engine tutorial which willwalk 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 tostore 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 SecretsEngine tutorial for a quicktour of Vault secrets engines.
You may notice other tutorials on our site using the kv
CLI commands witha different syntax ($ vault kv get secret/foo
instead of the$ vault kv get -mount=secret foo
that we've shown you here). Either stylewill have the same end result, but we recommend the more explicit -mount
flagsyntax when working with KV secrets engine v2, as it can avoid confusion laterwhen you need to refer to the secret by its full path (secret/data/foo
) whenwriting policies or raw API calls.
Help and reference
This tutorial only touched the basis of the Key/Value secrets engine. To learnmore about the features of Key/Value secrets engines, go through the followingtutorials:
- Versioned Key/Value Secrets Engine
- Static Secrets: Key/Value Secrets Engine