Config Opts From Environment

It is common and convenient in service management, especially container orchestration, to manage configuration settings using environment variables set by the controlling environment. This allows the service being managed to avoid extraneous files and other artifacts, allowing service immutability and thus straightforward elasticity. This specification proposes using the new drivers functionality provided by oslo.config to automatically support overriding or setting configuration from environment variables with standard and predictable names.

Problem description

A common way to pass instance specific settings to a container is to use shell environment variables. For example, in docker:

docker run -t -p \
  -e "DB_SYNC=True" \
  -e "AUTH_STRATEGY=noauth2" \

or in a (fragment of a) Kubernetes deployment:

    - name: myservice
      image: myservice
        - name: DB_SYNC
          value: "True"
        - name: AUTH_STRATEGY
          value: noauth2
      - containerPort: 80

In OpenStack these settings are usually managed by config files read by oslo.config into instances of ConfigOpts classes. At this time there is no unified way to use environment variables for these settings, meaning that in many cases if a deployer would like to run an OpenStack service in a container, they must provide a configuration file for that container, or provide some way for the service to gather configuration at run time.

The drivers functionality being developed for oslo.config provides one model for that run time configuration, but does not specifically address the case of using simple environment variables.

Proposed change

The spec proposes using the drivers model to create a ConfigurationSource for oslo.config that looks to the running environment for variables that match expected names for registered configuration settings. The source will be available by default, ideally coming second in the stack, after individual command line overrides, but before any files or other sources. If this proves impossible because of inter-dependencies in the file and command line handling, first in the stack is the second-best option.

The ConfigurationSource will translate config option names to candidate variable names. If those variables are set in the local environment (a member of os.environ in Python) the values will be returned. If they are not set, further processing of other sources will proceed.

There are two main challenges with this proposal. Resolving them in a satisfactory fashion is why this spec is being written. They are:

  1. Determining a satisfactory scheme for translating configuration option names to environment variable names in a way that is both predictable for humans and highly unlikely to collide with variable names that might otherwise be used. A strawman proposal is as follows:

    1. Prefix each variable with OS_

    2. Followed by the group: DEFAULT

    3. Separated from the name by a double-under __ (to allow unders in the group)

    4. Followed by the name, resulting in something like: OS_PLACEMENT_DATABASE__CONNECTION

    This will result in quite long names in some cases, but that’s likely going to be the case with any solution that satisfies both requirements. Note that this format can be transformed in both directions: from option group and name to environment variable name and vice versa.

  2. Individual options in a ConfigOpts have types. Environment variables, on the other hand, are strings. We either need to establish a way of coercing string-based representations of non-string types to the desired type (keystonemiddleware has some code that does some of this) or we perhaps initially only support StrOpt.

Here is a contrived example that describes two options which have similar names that demonstrates the importance of group handling. Configuration items as follows:

database_connection = foo

connection = bar



This is not something that has to be done in oslo.config. Individual services could manage their own environment checking, but that’s not really in keeping with the oslo principles nor the consistency goals of OpenStack.

In some circumstances an Opt could set a default that reads from the environment using default=os.environ.get('SOMETHING') but this has a critical disadvantage: The environment variable is only used if the option is not already set in the configuration. Ideally the environment variable should override configuration.

Another way to do this would be to add another parameter to Opt named envvar. If set, the value would be used to override the automatically generated environment variable name (as described above). This is considered undesirable as it made lead to published inconsistencies in variable naming.

Impact on Existing APIs

See above.

Security impact

There’s a slim chance that service behavior could change if pre-existing environment variables are present that happen to match the naming scheme described here.

Performance Impact

No significant performance impact is expected. Querying the environment is quick and the querying is done as needed, not for all possible configuration values.

Configuration Impact

No new options will be added when registering options. Support for environment variable-based overrides will be automatic.

Developer Impact

Developers will have an additional customization option available.

Testing Impact

Additional unit tests will be required to cover the added functionality.



Primary assignee:


Other contributors:



..TODO(cdent): figure this out

Work Items

  • Implement the new ConfigurationSource driver.

  • Integrate it as a default driver.

  • Update documentation.

  • Update the sample configuration generator to include the variable names.

  • Update the documentation generator to include the variable names.



Documentation Impact

The documentation will need to be updated to indicate that each option can be overridden with an environment variable and to describe how the name of the variable will be generated.


This implementation is dependent on the emerging drivers functionality in oslo.config.



This work is licensed under a Creative Commons Attribution 3.0 Unported License.