Oslo Configuration API

10.3.0 · active · verified Sat Apr 11

Oslo.config is a Python library from the OpenStack project that provides a robust API for parsing command-line arguments and .ini-style configuration files. It's a fundamental component for OpenStack services, offering a unified and flexible way to manage application settings. The library supports multiple configuration sources, including defaults, configuration files, environment variables, and command-line arguments, with a defined precedence order. The current version is 10.3.0, and it maintains an active release cadence tied to the OpenStack development cycle.

Warnings

gotcha Configuration sources have a strict precedence: Command-line arguments > Environment variables > Configuration files > Default values. Values from higher precedence sources will override lower ones.
Fix: Always remember the order of precedence when troubleshooting unexpected configuration values. Verify command-line arguments first, then environment variables, then configuration files.
gotcha oslo.config requires explicit parsing via `cfg.CONF()` to load values from command-line arguments or configuration files. If not called, only default values for registered options will be active.
Fix: Ensure `cfg.CONF(args=sys.argv[1:], ...)` is called early in your application's startup process to process command-line arguments and load configuration files.
gotcha When integrating with `oslo.log`, be aware of the distinction between `logging_default_format_string` and `logging_context_format_string`. Changes to one may not affect log lines using the other if an `oslo.context` object is attached.
Fix: If logging format changes aren't taking effect, check which format string is relevant to your log messages. Use `cfg.CONF.set_override()` or a configuration file to adjust both if needed.
gotcha While `oslo.config` (version 9.0.0 and newer) supports environment variables as a configuration source via predictable naming conventions (e.g., `OS_MYAPP__GROUP_OPTIONNAME`), older versions might not, or require manual `os.environ` checks.
Fix: For versions prior to 9.0.0, explicitly use `os.environ.get('ENV_VAR_NAME', default_value)` for environment-based configuration. For newer versions, ensure environment variables follow the `OS_PROJECT__GROUP_OPTIONNAME` pattern to be automatically picked up.

Install

pip install oslo.config Install latest version

Imports

cfg
```
from oslo_config import cfg
```
The primary configuration object is conventionally named `cfg.CONF` after import.

Quickstart

This quickstart demonstrates how to define configuration options, register them (both globally and within groups), and then parse values from a simulated configuration file and command-line arguments. It highlights the explicit parsing step required for oslo.config to load settings from external sources. The example also shows how to access the parsed configuration values.

import sys
from oslo_config import cfg
import os

# Define a configuration group and options
CONF = cfg.CONF
common_opts = [
    cfg.StrOpt('bind_host', default='0.0.0.0', help='IP address to listen on'),
    cfg.IntOpt('bind_port', default=8080, help='Port to listen on'),
    cfg.BoolOpt('debug', default=False, help='Enable debug logging')
]

# Register options
CONF.register_opts(common_opts, group='DEFAULT')

# You can also register options in a specific group
api_group = cfg.OptGroup(name='api', title='API Options')
CONF.register_group(api_group)
api_opts = [
    cfg.StrOpt('url', default='http://localhost:8080', help='Base URL for the API'),
    cfg.IntOpt('timeout', default=30, help='API request timeout in seconds')
]
CONF.register_opts(api_opts, group=api_group)

# Example config file content (save as 'app.conf')
# [DEFAULT]
# bind_host = 127.0.0.1
# debug = True
#
# [api]
# url = https://api.example.com

# Parse command line arguments and config files
# For testing, we simulate args and a config file
# In a real app, you'd use: CONF(sys.argv[1:], project='myproject', default_config_files=['/etc/myproject/app.conf'])

# Create a dummy config file for demonstration
config_file_path = 'app.conf'
with open(config_file_path, 'w') as f:
    f.write('[DEFAULT]\n')
    f.write('bind_host = 127.0.0.1\n')
    f.write('debug = True\n')
    f.write('\n[api]\n')
    f.write('url = https://api.example.com\n')

# Simulate CLI args (e.g., --debug=false --api-timeout=60)
sys_args = ['program_name', '--config-file', config_file_path, '--api-timeout', '60']

# oslo.config needs to be explicitly parsed. The first argument is the program name.
# We use os.environ.get for security (e.g., if a secret was passed as an env var)
CONF(args=sys_args[1:], project='myproject')

print(f"Bind Host: {CONF.bind_host}")
print(f"Bind Port: {CONF.bind_port}")
print(f"Debug Mode: {CONF.debug}")
print(f"API URL: {CONF.api.url}")
print(f"API Timeout: {CONF.api.timeout}")

# Clean up the dummy config file
os.remove(config_file_path)

view raw JSON →