README
¶
envconsul
envconsul provides a convienent way to populate values from Consul into an child process environment using the envconsul daemon.
The daemon envconsul allows applications to be configured with environmental variables, without having knowledge about the existence of Consul. This makes it especially easy to configure applications throughout all your environments: development, testing, production, etc.
envconsul is inspired by envdir in its simplicity, name, and function.
Installation
You can download a released envconsul artifact from the envconsul release page on GitHub. If you wish to compile from source, you will need to have buildtools and Go installed:
$ git clone https://github.com/hashicorp/envconsul.git
$ cd envconsul
$ make
This process will create bin/envconsul which make be invoked as a binary.
Usage
Options
| Option | Required | Description |
|---|---|---|
consul |
(required) | The location of the Consul instance to query (may be an IP address or FQDN) with port. |
token |
The Consul API token. | |
config |
The path to a configuration file on disk, relative to the current working directory. Values specified on the CLI take precedence over values specified in the configuration file | |
wait |
The minimum(:maximum) to wait before triggering a reload, separated by a colon (:). If the optional maximum value is omitted, it is assumed to be 4x the required minimum value. |
|
timeout |
The duration to wait for SIGTERM to finish before sending SIGKILL | |
sanitize |
Replace invalid characters in keys to underscores | |
upcase |
Convert all environment variable keys to uppercase | |
once |
Run envconsul once and exit (as opposed to the default behavior of daemon). |
Command Line
The CLI interface supports all of the options detailed above.
Query the nyc1 demo Consul instance, rending all the keys in config/redis, and printing the environment.
$ envconsul \
-consul demo.consul.io \
redis/config@nyc1 env
Query a local Consul instance, converting special characters in keys to undercores and uppercasing the keys:
$ envconsul \
-consul 127.0.0.1:8500 \
-sanitize \
-upcase \
redis/config env
Configuration File
The envconsul configuration file is written in HashiCorp Configuration Language (HCL). By proxy, this means the envconsul configuration file is JSON-compatible. For more information, please see the HCL specification.
The Configuration file syntax interface supports all of the options detailed above.
consul = "127.0.0.1:8500"
token = "abcd1234"
timeout = "5s"
sanitize = true
Commands specified on the command line take precedence over those defined in a config file!
Examples
Redis
Redis is a command key-value storage engine. If Redis is configured to read the given environment variables, you can use envconsul to start and manage the process:
$ envconsul \
-consul demo.consul.io \
redis/config service redis start
Env
This example is a great way to see envconsul in action. In practice, it is unlikely to be a useful use of envconsul though:
$ envconsul \
-consul=demo.consul.io \
redis/config env \
-once
ADDRESS=1.2.3.4
PORT=55
We can also ask envconsul to poll for configuration changes and automatically restar the process:
$ envconsul \
-consul=demo.consul.io \
redis/config /bin/sh -c "env; echo "-----"; sleep 1000"
ADDRESS=1.2.3.4
PORT=55
-----
ADDRESS=1.2.3.4
-----
ADDRESS=1.2.3.4
MAXCONNS=50
-----
Contributing
To hack on envconsul, you will need a modern Go environment. To compile the envconsul binary and run the test suite, simply execute:
$ make
This will compile the envconsul binary into bin/envconsul and run the test suite.
If you just want to run the tests:
$ make
Or to run a specific test in the suite:
go test ./... -run SomeTestFunction_name
Submit Pull Requests and Issues to the envconsul project on GitHub.
Documentation
¶
There is no documentation for this package.
Source Files