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
Pre-Compiled
-
Download a pre-compiled, released version from the envconsul releases page. You can download zip or tarball.
-
Extract the binary using
unzip
ortar
. -
Move the binary into your
$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
Vault
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 you try to read from a value that returns a map, for example.
The below steps used with PowerShell.
1. Create a non root token that has access to the secret/passwords
path (secret/data/passwords
if you are using KV2).
2. Assuming a secret exists at secret/passwords that was created like so:
$ .\vault.exe write secret/passwords username=foo password=bar
3. You must add the vault address and token information to the configuration file. The configuration can also be set via command-line 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"
}
4. envconsul
now can pull those values into the environment, or can also be set via command-line:
.\envconsul.exe -config="./config.txt" "cmd /C set"
You should see the below values in your output to confirm the environment variables are populated
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
You can also include your secrets path in the command line if you didn't set it up in your config file:
.\envconsul.exe -config="./config.txt" -secret="secret/passwords" - "cmd /C set"
To debug your output, 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.