Environment Variable Groups

Environment Variable Groups

Introduction and Use Cases

An environment variable group is a way of applying an an environment variable to every application running in the foundation. This can be very handy for things such as setting the HTTP_PROXY for apps, or for the applications built using the Mule buildpack, where specific settings are required for use in a local platform.

Note that these environment variable groups apply to every application after it has been restaged. There is not currently a way to apply them to a given set of applications, or to filter them by org/space.

There are two types of environment variable groups: Those that can be set for staging time and those that can be set for runtime. The distinction between these two is out of scope for this document.

Setting and Retrieving

These environment variable groups can be set/retrieved using the cf cli, as long as the user has the proper administrative permissions. To set a staging environment variable group, use

cf set-staging-environment-variable-group '{"tom":"tom", "mike":"mike"}'

or with a shortcut

cf ssevg '{"tom":"tom", "mike":"mike"}'

To retrieve the current staging environment group values, simply use

cf staging-environment-variable-group

or with a shortcut

cf sevg

The similar commands for the running environment variable group are

cf set-running-environment-variable-group
cf srevg


cf running-environment-variable-group
cf revg

Once these have been set, an application can be pushed an a cf env <app name> can be run to verify that the environment variables apply to that application.

Note that the input to the set commands is a JSON string. It is important to note that whatever is contained in the JSON string will be the entire set of the environment variables group. Consider the following set of commands:

cf ssevg '{"mike":"mike"}'
cf ssevg '{"tom":"tom"}'

There could be the expectation that the consecutive commands would be additive. In fact, they are not. The result of a subsequent cf sevg would only include {"tom":"tom"}

This becomes very important if there are multiple threads/pipelines updating an environment variable group. Each of these threads/pipelines needs to take the current environment variable group value and append their new value to that map.

The cf sevg/cf revg commands return a formatted version of the environment variable groups. Because these automation pipelines need to work against the JSON version of the output, they will need to call the cf api directly. A sample call would be

cf curl /v2/config/environment_variable_groups/running > /tmp/input.json

Once the JSON has been retrieved, it can be manipulated with the jq command-line utility. A sample query to add a name/value pair to a root JSON document might look something like

cat /tmp/input.json | jq ".  |= .+ {\"tom\":\"tom\"}" > /tmp/modified.json


Cloud Foundry Documentation

CF API Documentation

JSON Query Utility