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:

Type Option
oslo_config.types.String oslo_config.cfg.StrOpt
oslo_config.types.String oslo_config.cfg.SubCommandOpt
oslo_config.types.Boolean oslo_config.cfg.BoolOpt

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:

Name Description
name the option’s name
type the option’s type. Must be a callable object that takes string and returns converted and validated value
dest the name of the corresponding ConfigOpts property
short a single character CLI option name
default the default value of the option
positional True if the option is a positional CLI argument
metavar the option argument to show in –help
help an explanation of how the option is used
secret true if the value should be obfuscated in log output
required True if a value must be supplied for this option
deprecated_name deprecated name option. Acts like an alias
deprecated_group the group containing a deprecated alias
deprecated_opts list of DeprecatedOpt
sample_default a default string for sample config files
deprecated_for_removal indicates whether this opt is planned for removal in a future release
deprecated_reason indicates why this opt is planned for removal in a future release. Silently ignored if deprecated_for_removal is False
deprecated_since indicates which release this opt was deprecated in. Accepts any string, though valid version strings are encouraged. Silently ignored if deprecated_for_removal is False
mutable True if this option may be reloaded
advanced bool True/False value if this option has advanced usage and is not normally used by the majority of users

References

  1. oslo_config documentation
openstack python

Comments

comments powered by Disqus