Understanding oslo_config in OpenStack

The OpenStack Oslo library provides a set of Python libraries containing code shared by different OpenStack projects. This helps the many different OpenStack projects to follow a certain standard and convention when being developed.

In this post I want to go over oslo_config. This library helps with parsing of options found in configuration files or command line arguments.

Understanding Options

An option is defined using the Opt class or one of its sub-classes, from the cfg module:

from oslo_config import cfg

common_opts = [
    cfg.StrOpt('bind_host',
               default='0.0.0.0',
               help='IP address to listen on.'),
    cfg.Opt('bind_port',
            type=PortType,
            default=9292,
            help='Port number to listen on.')
]

In the example above we can see that we are using Opt and StrOpt, one of its sub-classes. You might notice that the second option's constructor has a type=PortType argument. This argument is a callable object that takes a string and either returns a value of that particular type, or raises ValueError if the value cannot be converted. The different types available can be found in the types module:

from oslo_config import types

PortType = types.Integer(1, 65535)

However, the predefined option sub-classes already set the option type. For example, the StrOpt option class above already sets the type to oslo_config.types.String. This table shows some relations between types and options:

Example: Gnocchi Dispatcher Options

A series of options for Gnocchi using oslo_config can be found in the Ceilometer source code at ceilometer/dispatcher/gnocchi_opts.py:

from oslo_config import cfg

dispatcher_opts = [
    cfg.BoolOpt('filter_service_activity',
                default=True,
                help='Filter out samples generated by Gnocchi '
                'service activity'),
    cfg.StrOpt('filter_project',
               default='gnocchi',
               help='Gnocchi project used to filter out samples '
               'generated by Gnocchi service activity'),
    cfg.StrOpt('archive_policy',
               deprecated_for_removal=True,
               deprecated_reason='Archive Policy Rule must be '
               'setup on Gnocchi side instead',
               help='The archive policy to use when the dispatcher '
               'create a new metric.'),
    cfg.StrOpt('resources_definition_file',
               default='gnocchi_resources.yaml',
               help=('The Yaml file that defines mapping between samples '
                     'and gnocchi resources/metrics')),
    cfg.FloatOpt('request_timeout', default=6.05, min=0.0,
                 help='Number of seconds before request to gnocchi times out'),
]

We can see that options can be given a default value (must match its type), help messages, minimum values, etc.

The example above shows another interesting concept: option deprecation. We can specify the reason why an option is being deprecated, and if it will be removed after deprecation.

Option Definitions

As we learned before, the base class for all configuration options is the Opts class. The only required parameter for this class is the option's name. However, the following is a list of all parameters that can be passed, some of then already seen in the example above:

References

1. oslo_config documentation