Launch a process with your secrets as environment variables

See Environment variables for reasons why you would want to pass configuration containing secrets as environment variables.

vault-cli can read secrets from the vault, turn them into environment variables and launch the process of your choice with those environment variables. This is how it works:

$ # Setting up a secret:
$ vault-cli set test/my_secret value=qwerty
Done

$ vault-cli env --envvar test/my_secret -- bash -c 'echo $MY_SECRET_VALUE'
qwerty

Environment variable naming

A path option looks like this:

$ vault-cli env --envvar [path/]{root}[:key][=prefix] [--envvar ...] -- {command...}

• The optional path/ allows you to indicate the location of the secret(s) you want to expose. If the root begins with a /, the base-path option will be ignored (see Access a special folder easily). This part of the path will not contribute to the environment variable name.

• The mandatory root element is either the name of a single secret object we want to expose, or the root path of a “secret directory” containing one or more secrets we want to expose recursively. The name of the environment variable starts with root.

• If root is a path to multiple secret objects, then the relative path between root and each secret object will be added to the environment variable name

• For each secret object, each key of the object will become an environment variable. the key is added to the environment variable name.

• If the flag --omit-single-key (or the environment variable VAULT_CLI_ENV_OMIT_SINGLE_KEY) is passed, then for each secret object, if it only has one key, the name of the key will not contribute to the environment variable name.

• You can limit a secret object to expose a single key by specifying :key. In this case, the environment variable name will just be the key.

• If a =prefix is provided, it replaces the root or :key part.

• Lastly, paths such as --envvar "", --envvar . or --envvar =prefix are valid to express “all the secrets under``base-path``”, although doing this can create a risk of exposing more secrets than intended. A sub-path is recommended in that case.

All parts of the secret environment variable name are uppercased, special characters /, - and `` `` (space) are changed to _. If an environment variable still contains characters that are not alphanumerical or _ after this transformation, a warning is raised, and this environment variable is skipped altogether.

Example

Let’s consider the vault contains only the following secret:

$ # Setting up a secret:
$ vault-cli set a/b c=mysecret
Done

This table maps input to output. Note that there will always be a single environment variable and its value will always be mysecret.

--envvar	--omit-single-key	environment variable name
a	False	A_B_C
a	True	A_B
a=D	False	D_B_C
a=D	True	D_B
a/b	False	B_C
a/b	True	B
a/b=D	False	D_C
a/b=D	True	D
a/b:c	True or False	C
a/b:c=D	True or False	D

Recommended setup

What we recommend as the ideal setup is the following:

• Application uses a prefix for all its environment variables (say MYAPP)

• All the secrets of the application are put under a common path named like the prefix (say myapp)

• Each secret is named like its corresponding environment variable (for MYAPP_GITHUB_TOKEN you’ll set myapp/github_token value=...)

• Each secret object usually holds a single key inside, whose value is a string, and --omit-single-key is used

• Groups of related configuration parameters are in the same secret object (say you now have MYAPP_GITHUB_TOKEN and MYAPP_GITHUB_URL, you’ll set myapp/github token=... url=...)

Your call would look like:

$ vault-cli env --omit-single-key --envvar myapp -- myapp

Ignoring errors

By default, vault-cli will not launch you program if an error happens during secrets collection. You can pass --force to ensure that your program will be launched, even if it will be missing some secrets.

$ vault-cli env --envvar myapp --force -- myapp