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.
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 127.0.0.1:8081:80 \ -e "DB_SYNC=True" \ -e "AUTH_STRATEGY=noauth2" \ myservice
or in a (fragment of a) Kubernetes deployment:
spec: containers: - name: myservice image: myservice env: - name: DB_SYNC value: "True" - name: AUTH_STRATEGY value: noauth2 ports: - 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.
The spec proposes using the drivers model to create a
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.
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:
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:
__(to allow unders in the group)
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.
ConfigOptshave 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
Here is a contrived example that describes two options which have similar names that demonstrates the importance of group handling. Configuration items as follows:
[placement] database_connection = foo [placement_database] connection = bar
would result in two environment variables
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
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.
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.
No significant performance impact is expected. Querying the environment is quick and the querying is done as needed, not for all possible configuration values.
No new options will be added when registering options. Support for environment variable-based overrides will be automatic.
Developers will have an additional customization option available.
Additional unit tests will be required to cover the added functionality.
..TODO(cdent): figure this out
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
This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode