Introduction
Envconsul provides a convenient way to launch a subprocess with environment variables populated from HashiCorp Consul and Vault. The tool is inspired by envdir and envchain, but works on many major operating systems with no runtime requirements. It is also available via a Docker container for scheduled environments.
Envconsul supports 12-factor applications which get their configuration via the environment. Environment variables are dynamically populated from Consul or Vault, but the application is unaware; applications just read environment variables. This enables flexibility and portability for applications across systems.
Installation
-
Download a release version from the envconsul releases page. It may be downloaded as a zip or tarball.
-
Extract the binary using
unzip
ortar
. -
Move the binary into the one of the appropriate directories that are part of the system
$PATH
Usage
For the full list of command-line options:
$ .\envconsul.exe -h
Command Line Interface (CLI)
The Envconsul CLI interface supports most of the options in the configuration file and visa-versa. Here are some common examples of CLI usage.
Configuration File
Configuration files are written in the HashiCorp Configuration Language. By proxy, this means the configuration is also JSON compatible. For more information about config file flags click here.
Examples
With the Vault integration, it is possible to pull secrets from Vault directly into the environment using envconsul
. The only restriction is that the data must be "flat" and all keys and values must be strings or string-like values. envconsul
will return an error if attempting to read from a value that returns a map, for example.
The below steps are within a Windows PowerShell prompt.
- Create a non root token that has access to the
secret/passwords
path (secret/data/passwords
if using KV2). - Assuming a secret exists at secret/passwords that was created like so:
$ .\vault.exe write secret/passwords username=foo password=bar
- Add the vault address and token information to the configuration file. The configuration can also be set via CLI flags to
envconsul
:#For dev, localhost Vault
vault {
address = "http://127.0.0.1:8200"
token = "abcd1234"
# For Windows may also be specified via the $env:VAULT_TOKEN="Token"
renew_token = true
}
secret {
path = "secret/passwords"
# For KV-V2 Secrets use path = "secret/data/passwords"
} -
envconsul
can now pull those values into the environment or it can also be set via CLI:
.\envconsul.exe -config="./config.txt" "cmd /C set"
The output values can be checked using the populated environment variables to verify
secret_passwords_username=foo
secret_passwords_password=bar
Notice that the environment variables are prefixed with the path. The slashes in the path are converted to underscores, followed by the key:
secret/passwords => secret_passwords
mysql/creds/readonly => mysql_creds_readonly
This behavior may be disabled by setting no_prefix
as shown in the config file below:
secret {
no_prefix = true
path = "secret/passwords"
}
Output will be username=foo
& password=bar
It's possible to include the secrets path in the CLI if wasn't set it up in the config file:
.\envconsul.exe -config="./config.txt" -secret="secret/passwords" - "cmd /C set"
To debug outputs, add -log-level="debug"
:
.\envconsul.exe -config="./config.txt" -secret="secret/passwords" -log-level="debug" "cmd /C set"
For more information please check the github official documentation.