Documentation

Getting Started

Environr has two parts – a web-based console and a CLI. Using the console you can:

• Create credentials to authorize access by the CLI tool
• Add config sets, comprised of named groups of environment variables
• Lock / unlock config sets to prevent modification

Once a set of credentials has been created, you can use the CLI tool to:

• Import existing environment variables in YAML format
• Fetch a set of named environment variables and output them in a number of formats

The latest version of the CLI tool can always be downloaded below:

macOS
Linux
Windows

After creating a set of credentials in the console, you can configure the CLI by running

envionr-cli configure

or by exporting the environment variables in your shell

export ENVIRONR_API_KEY=...  
export ENVIRONR_API_SECRET=...

The former creates a file at $HOME/.environr/credentials and associates a profile name with the given API key and secret. This method (or the manual creation of that file) is the preferred way to configure the CLI tool because it avoids adding the API secret to the shell’s history.

Using the credentials file also means multiple accounts can be configured and then selected at run-time by:

environr-cli --profile myprofile ...

Importing existing environments

If you already have a set of environment variables defined in a configuration file, you can import these into Environr without adding each one manually in the console.

To import, create a single level YAML file where each environment variable is defined like this:

variable_name: variable_value
another_name: another_value

Then, import this file using:

environr-cli --profile [profile] import [name] [filename]

Here, [name] refers to the name you’ll give your newly created configuration set and how you’ll identify it when accessing in the next step.

You can re-import at any time to overwrite the configuration set with the newly defined variables.

If the configuration set is locked, an error will be returned.

Fetching configuration sets

A core function of Environr is the ability to fetch named configuration sets using the CLI. By default, fetching a configuration set without any options returns each environment variable and value separated by = and terminated by a newline. This is compatible with typical Bash-style shell scripting and Docker’s --env-file parameter.

environr-cli --profile [profile] env [name]

There are several other output formats, including JSON, YAML, and oneline, which can be specified with the --env-output parameters.

json: returns the environment variables formatted as JSON
yaml: returns the environment variables formatted as YAML
oneline returns the environment variable and values separated by = but terminated by a single space, putting all variables on a single line

Example usage scenarios

Kubernetes

There are several ways you can inject environment variables into Kubernetes using Environr. The first example we’ll look at is using the --env-output parameter to generate a Kubernetes ConfigMap. To begin, make sure you’ve already created a configuration in the Environr console and then:

environr-cli env [name] --env-output kubernetes-configmap > config-map.yaml

Inspecting the ConfigMap shows a Kubernetes-native ConfigMap with the given config name and each key-value pair as the data.

You can also apply the ConfigMap to your current cluster context with one command:

kubectl apply -f <(environr-cli env [name] --env-output kubernetes-configmap)

Another way to interact with Kubernetes is with Helm. By outputting the environment as YAML, you can use the output of environr-cli as a values.yaml file.

helm upgrade --install -f <(environr-cli env [name] --env-output yaml)

Or, use a configuration as a Secret resource:

helm upgrade --install -f <(environr-cli env [name] --env-output yamlhead=global.secrets)

By using yamlhead=path.to.follow we nest our configuration values inside arbitrary YAML. This is convenient when we have a Helm template that looks something like this:

apiVersion: v1
kind: Secret
metadata:
  name: app-secret
type: Opaque
data:
  username: {{ .global.secrets.username | b64enc }}
  password: {{ .global.secrets.password | b64enc }}

The output from the Helm template would have our .global.secrets values injected in the appropriate places.

AWS Elastic Beanstalk

Environment variables can be set in the Elastic Beanstalk console or by using the AWS CLI. Unfortunately, there aren’t any safeguards in place to avoid accidentally modifying these values once they’ve been set and managing them in the console can be somewhat clumsy.

1. Create a set of credentials in the Environr console named elastic-beanstalk
2. Add the ENVIRONR_API_KEY and ENVIRONR_API_SECRET environment variables to your Elastic Beanstalk environment
3. Create a configuration set in the Environr console that holds your actual configuration
4. Lock the configuration set in the Environr console
5. Inject the environment variables from Environr into your application using a run script like so:
   

#!/usr/bin/env bash

env $(environr-cli env --env-output oneline [config set name]) /path/to/application

Your application will have access to the environment variables from your [config set name] and those variables can not be changed without unlocking them from the Environr console.

CircleCI

If you’re managing the configuration of your application using environment variables, propagating every change to other developers, your CI/CD platforms (Jenkins, CircleCI, etc.), and other environments can be irritating and prone to errors. Instead, use Environr to provide credentialed access to configuration sets and make your environment changes in a centralized location.

1. Create a set of credentials in the Environr console for CircleCI
2. Add the ENVIRONR_API_KEY and ENVIRONR_API_SECRET environment variables to your CircleCI configuration (not in circle.yaml!)
3. Create a configuration set in the Environr console that holds your actual configuration
4. Choose to lock or keep your configuration unlocked
5. Inject the environment variables from Environr into your test suite:
   

env $(environr-cli env --env-output oneline [config set name]) ./manage.py test

Local development

While the examples above will work just as well for local development, sometimes more flexibility is necessary. Running Docker commands locally may need access to a configuration set using the --env-file parameter which we can easily support with:

> environr-cli env --env-output multiline [config set name] > environment-file
> docker run --rn -it --env-file environment-file busybox sh -cf 'echo My Environment && env'