Envconsul provides a convenient way to launch a subprocess with environment variables populated from HashiCorp [Consul][consul] and [Vault][vault]. The tool is inspired by [envdir][envdir] and [envchain][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][12-factor] 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 extreme flexibility and portability for applications across systems.

The documentation in this README corresponds to the main branch of envconsul. It may contain unreleased features or different APIs than the most recently released version. Please see the Git tag that corresponds to your version of envconsul for the proper documentation.

Community Support

If you have questions about how envconsul works, its capabilities or anything other than a bug or feature request (use github's issue tracker for those), please see our community support resources.

Community portal: https://discuss.hashicorp.com/tags/c/consul/29/envconsul

Other resources: https://www.consul.io/community.html

Additionally, for issues and pull requests, we'll be using the :+1: reactions as a rough voting system to help gauge community priorities. So please add :+1: to any issue or pull request you'd like to see worked on. Thanks.

Installation

Pre-Compiled

Download a pre-compiled, released version from the [envconsul releases][releases] page. You can download zip or tarball.
Extract the binary using unzip or tar.
Move the binary into your $PATH.

To compile from source, please see the instructions in the contributing section.

From Source (Go)

Install common build tools and [go][go].

Clone the repository from GitHub.

$ git clone https://github.com/hashicorp/envconsul.git
$ cd envconsul

Run the development make target.
```
$ make dev
```

Or run the make target for your platform and architecture.

$ make darwin/amd64 # or linux/amd64 or windows/amd64, etc

This process will build envconsul into pkg/OS_ARCH. You can move this into your path or execute it directly.

Quick Example

This short example assumes Consul is installed locally.

Start a Consul cluster in dev mode.
```
$ consul agent -dev
```

Write some data.

$ consul kv put my-app/address 1.2.3.4
$ consul kv put my-app/port 80
$ consul kv put my-app/max_conns 5

Execute envconsul with a subprocess (env in this example).
```
$ envconsul -prefix my-app env
```
Envconsul will connect to Consul, read the data from the key-value store, and populate environment variables corresponding to those values. Here is sample output.
```
address=1.2.3.4
max_conns=5
port=80
```

For more examples and use cases, please see the examples in this README.

Usage

For the full list of command-line options:

$ envconsul -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. For the full list of options, please run envconsul -h.

Render data from the prefix my-app into the environment.

$ envconsul -prefix my-app ruby my-app.rb

Render only data from the two prefixes into the environment (the parent processes environment will not be copied).

$ envconsul -pristine -prefix common -prefix my-app yarn start

Convert environment variables to upcase and remove any non-standard keys (like dashes to underscores).

$ envconsul -upcase -sanitize -prefix my-app python my-app.my

Read information about service.

$ envconsul -service-query my-service

Read secrets from Vault.

$ envconsul -secret secret/my-app ./my-app

Configuration File

Configuration files are written in the [HashiCorp Configuration Language][hcl]. By proxy, this means the configuration is also JSON compatible.

# This denotes the start of the configuration section for Consul. All values
# contained in this section pertain to Consul.
consul {
  # This block specifies the basic authentication information to pass with the
  # request. For more information on authentication, please see the Consul
  # documentation.
  auth {
    enabled  = true
    username = "test"
    password = "test"
  }

  # This is the address of the Consul agent. By default, this is
  # 127.0.0.1:8500, which is the default bind and port for a local Consul
  # agent. It is not recommended that you communicate directly with a Consul
  # server, and instead communicate with the local Consul agent. There are many
  # reasons for this, most importantly the Consul agent is able to multiplex
  # connections to the Consul server and reduce the number of open HTTP
  # connections. Additionally, it provides a "well-known" IP address for which
  # clients can connect.
  address = "127.0.0.1:8500"

  # This is the ACL token to use when connecting to Consul. If you did not
  # enable ACLs on your Consul cluster, you do not need to set this option.
  #
  # This option is also available via the environment variable CONSUL_TOKEN.
  token = "abcd1234"

  # This controls the retry behavior when an error is returned from Consul.
  # Envconsul is highly fault tolerant, meaning it does not exit in the face
  # of failure. Instead, it uses exponential back-off and retry functions
  # to wait for the cluster to become available, as is customary in distributed
  # systems.
  retry {
    # This enabled retries. Retries are enabled by default, so this is
    # redundant.
    enabled = true

    # This specifies the number of attempts to make before giving up. Each
    # attempt adds the exponential backoff sleep time. Setting this to
    # zero will implement an unlimited number of retries.
    attempts = 12

    # This is the base amount of time to sleep between retry attempts. Each
    # retry sleeps for an exponent of 2 longer than this base. For 5 retries,
    # the sleep times would be: 250ms, 500ms, 1s, 2s, then 4s.
    backoff = "250ms"

    # This is the maximum amount of time to sleep between retry attempts.
    # When max_backoff is set to zero, there is no upper limit to the
    # exponential sleep between retry attempts.
    # If max_backoff is set to 10s and backoff is set to 1s, sleep times
    # would be: 1s, 2s, 4s, 8s, 10s, 10s, ...
    max_backoff = "1m"
  }

  # This block configures the SSL options for connecting to the Consul server.
  ssl {
    # This enables SSL. Specifying any option for SSL will also enable it.
    enabled = true

    # This enables SSL peer verification. The default value is "true", which
    # will check the global CA chain to make sure the given certificates are
    # valid. If you are using a self-signed certificate that you have not added
    # to the CA chain, you may want to disable SSL verification. However, please
    # understand this is a potential security vulnerability.
    verify = false

    # This is the path to the certificate to use to authenticate. If just a
    # certificate is provided, it is assumed to contain both the certificate and
    # the key to convert to an X509 certificate. If both the certificate and
    # key are specified, Envconsul will automatically combine them into an X509
    # certificate for you.
    cert = "/path/to/client/cert"
    key  = "/path/to/client/key"

    # This is the path to the certificate authority to use as a CA. This is
    # useful for self-signed certificates or for organizations using their own
    # internal certificate authority.
    ca_cert = "/path/to/ca"

    # This is the path to a directory of PEM-encoded CA cert files. If both
    # `ca_cert` and `ca_path` is specified, `ca_cert` is preferred.
    ca_path = "path/to/certs/"

    # This sets the SNI server name to use for validation.
    server_name = "my-server.com"
  }
}

# This block defines the configuration of the child process to execute and
# manage.
exec {
  # This is the command to execute as a child process. There can be only one
  # command per process.
  command = "/usr/bin/app"

  # This is a random splay to wait before killing the command. The default
  # value is 0 (no wait), but large clusters should consider setting a splay
  # value to prevent all child processes from reloading at the same time when
  # data changes occur. When this value is set to non-zero, Envconsul will wait
  # a random period of time up to the splay value before killing the child
  # process. This can be used to prevent the thundering herd problem on
  # applications that do not gracefully reload.
  splay = "5s"

  env {
    # This specifies if the child process should not inherit the parent
    # process's environment. By default, the child will have full access to the
    # environment variables of the parent. Setting this to true will send only
    # the values specified in `custom_env` to the child process.
    pristine = false

    # This specifies additional custom environment variables in the form shown
    # below to inject into the child's runtime environment. If a custom
    # environment variable shares

Envconsul

Install / Use

README