{"id":4162,"library":"oslo-config","title":"Oslo Configuration API","description":"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.","status":"active","version":"10.3.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/oslo.config","tags":["OpenStack","configuration","CLI","INI files","settings","config-parsing"],"install":[{"cmd":"pip install oslo.config","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Commonly used alongside oslo.config for unified logging configuration within OpenStack projects.","package":"oslo.log","optional":false},{"reason":"Used for internationalization and localization of messages and help strings within configuration options.","package":"oslo.i18n","optional":true},{"reason":"Used for managing extensible components and drivers, which oslo.config can leverage for configuration sources.","package":"stevedore","optional":true},{"reason":"A utility library used by Oslo projects for managing deprecated code paths.","package":"debtcollector","optional":true}],"imports":[{"note":"The primary configuration object is conventionally named `cfg.CONF` after import.","symbol":"cfg","correct":"from oslo_config import cfg"}],"quickstart":{"code":"import sys\nfrom oslo_config import cfg\nimport os\n\n# Define a configuration group and options\nCONF = cfg.CONF\ncommon_opts = [\n    cfg.StrOpt('bind_host', default='0.0.0.0', help='IP address to listen on'),\n    cfg.IntOpt('bind_port', default=8080, help='Port to listen on'),\n    cfg.BoolOpt('debug', default=False, help='Enable debug logging')\n]\n\n# Register options\nCONF.register_opts(common_opts, group='DEFAULT')\n\n# You can also register options in a specific group\napi_group = cfg.OptGroup(name='api', title='API Options')\nCONF.register_group(api_group)\napi_opts = [\n    cfg.StrOpt('url', default='http://localhost:8080', help='Base URL for the API'),\n    cfg.IntOpt('timeout', default=30, help='API request timeout in seconds')\n]\nCONF.register_opts(api_opts, group=api_group)\n\n# Example config file content (save as 'app.conf')\n# [DEFAULT]\n# bind_host = 127.0.0.1\n# debug = True\n#\n# [api]\n# url = https://api.example.com\n\n# Parse command line arguments and config files\n# For testing, we simulate args and a config file\n# In a real app, you'd use: CONF(sys.argv[1:], project='myproject', default_config_files=['/etc/myproject/app.conf'])\n\n# Create a dummy config file for demonstration\nconfig_file_path = 'app.conf'\nwith open(config_file_path, 'w') as f:\n    f.write('[DEFAULT]\\n')\n    f.write('bind_host = 127.0.0.1\\n')\n    f.write('debug = True\\n')\n    f.write('\\n[api]\\n')\n    f.write('url = https://api.example.com\\n')\n\n# Simulate CLI args (e.g., --debug=false --api-timeout=60)\nsys_args = ['program_name', '--config-file', config_file_path, '--api-timeout', '60']\n\n# oslo.config needs to be explicitly parsed. The first argument is the program name.\n# We use os.environ.get for security (e.g., if a secret was passed as an env var)\nCONF(args=sys_args[1:], project='myproject')\n\nprint(f\"Bind Host: {CONF.bind_host}\")\nprint(f\"Bind Port: {CONF.bind_port}\")\nprint(f\"Debug Mode: {CONF.debug}\")\nprint(f\"API URL: {CONF.api.url}\")\nprint(f\"API Timeout: {CONF.api.timeout}\")\n\n# Clean up the dummy config file\nos.remove(config_file_path)\n","lang":"python","description":"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."},"warnings":[{"fix":"Always remember the order of precedence when troubleshooting unexpected configuration values. Verify command-line arguments first, then environment variables, then configuration files.","message":"Configuration sources have a strict precedence: Command-line arguments > Environment variables > Configuration files > Default values. Values from higher precedence sources will override lower ones.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (especially when using oslo.log)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<9.0.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}