Your First Secret

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.

Start Interactive Lab

»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:

»Get command help

You can interact with key/value secrets engine using the vault kv command. Get the 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 secret/foo bar=baz

  Read this value back:

      $ vault kv get secret/foo

  Get metadata for the key:

      $ vault kv metadata get secret/foo

  Get a specific version of the key:

      $ vault kv get -version=1 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

$ 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 secret/foo bar=baz
  Read this value back:
      $ vault kv get secret/foo
  Get metadata for the key:
      $ vault kv metadata get secret/foo
  Get a specific version of the key:
      $ vault kv get -version=1 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

»Write a secret

Before you begin, check the command help.

$ vault kv put -help

$ vault kv put -help

The help provides command examples along with optional parameters that you can use.

Now, write a secret foo with value of world to the path secret/hello using the 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       2022-01-15T01:40:03.740833Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

$ vault kv put secret/hello foo=world
Key                Value---                -----created_time       2022-01-15T01:40:03.740833Zcustom_metadata    <nil>deletion_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       2022-01-15T01:40:09.888293Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

$ vault kv put secret/hello foo=world excited=yes
Key                Value---                -----created_time       2022-01-15T01:40:09.888293Zcustom_metadata    <nil>deletion_time      n/adestroyed          falseversion            2

Notice that the version is now 2.

»Read 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       2022-01-15T01:40:09.888293Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

===== Data =====
Key        Value
---        -----
excited    yes
foo        world

$ vault kv get 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

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.

$ vault kv get -field=excited secret/hello

yes

$ 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 excited secret.

$ vault kv get -format=json secret/hello | jq -r .data.data.excited

yes

$ vault kv get -format=json secret/hello | jq -r .data.data.excited
yes

»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.

$ vault kv delete secret/hello

Success! Data deleted (if it existed) at: secret/hello

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

Try to read the secret you just deleted.

$ vault kv get secret/hello

======= Metadata =======
Key                Value
---                -----
created_time       2022-01-15T01:40:09.888293Z
custom_metadata    <nil>
deletion_time      2022-01-15T01:40:41.786995Z
destroyed          false
version            2

$ vault kv get secret/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 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.

$ vault kv undelete -versions=2 secret/hello

Success! Data written to: secret/undelete/hello

$ vault kv undelete -versions=2 secret/hello
Success! Data written to: secret/undelete/hello

Now, the data is recovered.

$ vault kv get secret/hello

======= Metadata =======
Key                Value
---                -----
created_time       2022-01-15T01:40:09.888293Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

===== Data =====
Key        Value
---        -----
excited    yes
foo        world

$ vault kv get 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

»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 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:

• Versioned Key/Value Secrets Engine
• Static Secrets: Key/Value Secrets Engine