diff options
Diffstat (limited to 'doc/source/reference')
| -rw-r--r-- | doc/source/reference/builtins.rst | 5 | ||||
| -rw-r--r-- | doc/source/reference/cfg.rst | 5 | ||||
| -rw-r--r-- | doc/source/reference/cfgfilter.rst | 5 | ||||
| -rw-r--r-- | doc/source/reference/configopts.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/exceptions.rst | 20 | ||||
| -rw-r--r-- | doc/source/reference/faq.rst | 98 | ||||
| -rw-r--r-- | doc/source/reference/fixture.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/helpers.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 24 | ||||
| -rw-r--r-- | doc/source/reference/mutable.rst | 121 | ||||
| -rw-r--r-- | doc/source/reference/namespaces.rst | 12 | ||||
| -rw-r--r-- | doc/source/reference/opts.rst | 25 | ||||
| -rw-r--r-- | doc/source/reference/parser.rst | 11 | ||||
| -rw-r--r-- | doc/source/reference/sphinxconfiggen.rst | 50 | ||||
| -rw-r--r-- | doc/source/reference/sphinxext.rst | 60 | ||||
| -rw-r--r-- | doc/source/reference/styleguide.rst | 84 | ||||
| -rw-r--r-- | doc/source/reference/types.rst | 6 |
17 files changed, 550 insertions, 0 deletions
diff --git a/doc/source/reference/builtins.rst b/doc/source/reference/builtins.rst new file mode 100644 index 0000000..fc80f74 --- /dev/null +++ b/doc/source/reference/builtins.rst @@ -0,0 +1,5 @@ +================== + Built-in Options +================== + +.. show-options:: oslo.config diff --git a/doc/source/reference/cfg.rst b/doc/source/reference/cfg.rst new file mode 100644 index 0000000..5e3f988 --- /dev/null +++ b/doc/source/reference/cfg.rst @@ -0,0 +1,5 @@ +-------------- +The cfg Module +-------------- + +.. automodule:: oslo_config.cfg diff --git a/doc/source/reference/cfgfilter.rst b/doc/source/reference/cfgfilter.rst new file mode 100644 index 0000000..c11cddd --- /dev/null +++ b/doc/source/reference/cfgfilter.rst @@ -0,0 +1,5 @@ +-------------------- +The cfgfilter Module +-------------------- + +.. automodule:: oslo_config.cfgfilter diff --git a/doc/source/reference/configopts.rst b/doc/source/reference/configopts.rst new file mode 100644 index 0000000..06c9c3b --- /dev/null +++ b/doc/source/reference/configopts.rst @@ -0,0 +1,8 @@ +-------------------- +The ConfigOpts Class +-------------------- + +.. currentmodule:: oslo_config.cfg + +.. autoclass:: ConfigOpts + :members: diff --git a/doc/source/reference/exceptions.rst b/doc/source/reference/exceptions.rst new file mode 100644 index 0000000..8036b84 --- /dev/null +++ b/doc/source/reference/exceptions.rst @@ -0,0 +1,20 @@ +---------- +Exceptions +---------- + +.. currentmodule:: oslo_config.cfg + +.. autoexception:: Error +.. autoexception:: NotInitializedError +.. autoexception:: ArgsAlreadyParsedError +.. autoexception:: NoSuchOptError +.. autoexception:: NoSuchGroupError +.. autoexception:: DuplicateOptError +.. autoexception:: RequiredOptError +.. autoexception:: TemplateSubstitutionError +.. autoexception:: ConfigFilesNotFoundError +.. autoexception:: ConfigFilesPermissionDeniedError +.. autoexception:: ConfigDirNotFoundError +.. autoexception:: ConfigFileParseError +.. autoexception:: ConfigFileValueError +.. autoexception:: DefaultValueError diff --git a/doc/source/reference/faq.rst b/doc/source/reference/faq.rst new file mode 100644 index 0000000..2171d13 --- /dev/null +++ b/doc/source/reference/faq.rst @@ -0,0 +1,98 @@ +============================ + Frequently Asked Questions +============================ + +Why does oslo.config have a CONF object? Global objects SUCK! +============================================================= + +.. original source: https://wiki.openstack.org/wiki/Oslo#Why_does_oslo.config_have_a_CONF_object.3F_Global_object_SUCK.21 + +Indeed. Well, it's a long story and well documented in mailing list +archives if anyone cares to dig up some links. + +Around the time of the Folsom Design Summit, an attempt was made to +remove our dependence on a global object like this. There was massive +debate and, in the end, the rough consensus was to stick with using +this approach. + +Nova, through its use of the gflags library, used this approach from +`commit zero +<https://github.com/openstack/nova/blob/bf6e6e7/nova/flags.py#L27>`__. Some +OpenStack projects didn't initially use this approach, but most now +do. The idea is that having all projects use the same approach is more +important than the objections to the approach. Sharing code between +projects is great, but by also having projects use the same idioms for +stuff like this it makes it much easier for people to work on multiple +projects. + +This debate will probably never completely go away, though. See `this +latest discussion in August, 2014 +<http://lists.openstack.org/pipermail/openstack-dev/2014-August/044050.html>`__ + +Why are configuration options not part of a library's API? +========================================================== + +Configuration options are a way for deployers to change the behavior +of OpenStack. Applications are not supposed to be aware of the +configuration options defined and used within libraries, because the +library API is supposed to work transparently no matter which backend +is configured. + +Configuration options in libraries can be renamed, moved, and +deprecated just like configuration options in applications. However, +if applications are allowed to read or write the configuration options +directly, treating them as an API, the option cannot be renamed +without breaking the application. Instead, libraries should provide a +programmatic API (usually a :func:`set_defaults` function) for setting +the defaults for configuration options. For example, this function +from ``oslo.log`` lets the caller change the format string and default +logging levels: + +:: + + def set_defaults(logging_context_format_string=None, + default_log_levels=None): + """Set default values for the configuration options used by oslo.log.""" + # Just in case the caller is not setting the + # default_log_level. This is insurance because + # we introduced the default_log_level parameter + # later in a backwards in-compatible change + if default_log_levels is not None: + cfg.set_defaults( + _options.log_opts, + default_log_levels=default_log_levels) + if logging_context_format_string is not None: + cfg.set_defaults( + _options.log_opts, + logging_context_format_string=logging_context_format_string) + +If the name of either option changes, the API of :func:`set_defaults` +can be updated to allow both names, and warn if the old one is +provided. Using a supported API like this is better than having an +application call :func:`set_default` on the configuration object +directly, such as: + +:: + + cfg.CONF.set_default('default_log_levels', default_log_levels) + +This form will trigger an error if the logging options are moved out +of the default option group into their own section of the +configuration file. It will also fail if the ``default_log_levels`` +option is not yet registered, or if it is renamed. All of those cases +can be protected against with a :func:`set_defaults` function in the +library that owns the options. + +Similarly, code that does not *own* the configuration option +definition should not read the option value. An application should +never, for example, do something like: + +:: + + log_file = cfg.CONF.log_file + +The type, name, and existence of the ``log_file`` configuration option +is subject to change. ``oslo.config`` makes it easy to communicate +that change to a deployer in a way that allows their old configuration +files to continue to work. It has no mechanism for doing that in +application code, however. diff --git a/doc/source/reference/fixture.rst b/doc/source/reference/fixture.rst new file mode 100644 index 0000000..47c4939 --- /dev/null +++ b/doc/source/reference/fixture.rst @@ -0,0 +1,8 @@ +------------ +Test Fixture +------------ + +.. currentmodule:: oslo_config.fixture + +.. autoclass:: Config + :members: diff --git a/doc/source/reference/helpers.rst b/doc/source/reference/helpers.rst new file mode 100644 index 0000000..e2d5cb4 --- /dev/null +++ b/doc/source/reference/helpers.rst @@ -0,0 +1,8 @@ +---------------- +Helper Functions +---------------- + +.. currentmodule:: oslo_config.cfg + +.. autofunction:: find_config_files +.. autofunction:: set_defaults diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 0000000..23f2d3c --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,24 @@ +=================== + Using oslo.config +=================== + +.. toctree:: + :maxdepth: 2 + + cfg + opts + types + configopts + cfgfilter + helpers + fixture + parser + exceptions + namespaces + styleguide + mutable + builtins + sphinxext + sphinxconfiggen + faq + diff --git a/doc/source/reference/mutable.rst b/doc/source/reference/mutable.rst new file mode 100644 index 0000000..ba89a16 --- /dev/null +++ b/doc/source/reference/mutable.rst @@ -0,0 +1,121 @@ +Enabling your project for mutable config +======================================== + +As of OpenStack Newton, config options can be marked as 'mutable'. This means +they can be reloaded (usually via SIGHUP) at runtime, without a service +restart. However, each project has to be enabled before this will work and some +care needs to be taken over how each option is used before it can safely be +marked mutable. + +.. contents:: Table of Contents + :local: + + +Calling mutate_config_files +--------------------------- + +Config mutation is triggered by ``ConfigOpts#mutate_config_files`` being +called. Services launched with oslo.service get a signal handler on SIGHUP but +by default that calls the older ``ConfigOpts#reload_config_files`` method. To +get the new behaviour, we have to pass ``restart_method='mutate'``. For +example:: + + service.ProcessLauncher(CONF, restart_method='mutate') + +An example patch is here: https://review.openstack.org/#/c/280851 + +Some projects may call ``reload_config_files`` directly, in this case just +change that call to ``mutate_config_files``. If there is no signal handler or +you want to trigger reload by a different method, maybe via a web UI or +watching a file, just ensure your trigger calls ``mutate_config_files``. + + + +Making options mutable-safe +--------------------------- + +When options are mutated, they change in the ConfigOpts object but this will +not necessarily affect your service immediately. There are three main cases to +deal with: + +* The option is checked every time +* The option is cached on the stack +* The option affects state + + +The option is checked every time +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This pattern is already safe. Example code:: + + while True: + progress_timeout = CONF.libvirt.live_migration_progress_timeout + completion_timeout = int( + CONF.libvirt.live_migration_completion_timeout * data_gb) + if libvirt_migrate.should_abort(instance, now, progress_time, + progress_timeout, completion_timeout): + guest.abort_job() + + +The option is cached on the stack +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Just putting the option value in a local variable is enough to cache it. This +is tempting to do with loops. Example code:: + + progress_timeout = CONF.libvirt.live_migration_progress_timeout + completion_timeout = int( + CONF.libvirt.live_migration_completion_timeout * data_gb) + while True: + if libvirt_migrate.should_abort(instance, now, progress_time, + progress_timeout, completion_timeout): + guest.abort_job() + +The goal is to check the option exactly once every time it could have an +effect. Usually this is as simple as checking it every time, for example by +moving the locals into the loop. Example patch: +https://review.openstack.org/#/c/319203 + +Sometimes multiple computations have to be performed using the option values +and it's important that the result is consistent. In this case, it's necessary +to cache the option values in locals. Example patch: +https://review.openstack.org/#/c/319254 + + +The option affects state +^^^^^^^^^^^^^^^^^^^^^^^^ + +An option value can also be cached, after a fashion, by state - either system +or external. For example, the 'debug' option of oslo.log is used to set the +default log level on startup. The option is not normally checked again, so if +it is mutated, the system state will not reflect the new value of the option. +In this case we have to use a *mutate hook*:: + + def _mutate_hook(conf, fresh): + if (None, 'debug') in fresh: + if conf.debug: + log_root.setLevel(logging.DEBUG) + + def register_options(conf): + ... snip ... + conf.register_mutate_hook(_mutate_hook) + +Mutate hook functions will be passed two positional parameters, 'conf' and +'fresh'. 'conf' is a reference to the updated ConfigOpts object. 'fresh' looks +like:: + + { (group, option_name): (old_value, new_value), ... } + +for example:: + + { (None, 'debug'): (False, True), + ('libvirt', 'live_migration_progress_timeout'): (50, 75) } + +Hooks may be called in any order. + +Each project should register one hook, which does whatever is necessary to +apply all the new option values. This hook function could grow very large. For +good style, modularise the hook using secondary functions rather than accreting +a monolith or registering multiple hooks. + +Example patch: https://review.openstack.org/#/c/254821/ diff --git a/doc/source/reference/namespaces.rst b/doc/source/reference/namespaces.rst new file mode 100644 index 0000000..6c5f32a --- /dev/null +++ b/doc/source/reference/namespaces.rst @@ -0,0 +1,12 @@ +---------------------------------------------- +Choosing group names for configuration options +---------------------------------------------- + +Applications should use a meaningful name without a prefix. For Oslo +libraries, when naming groups for configuration options using the +name of the library itself instead of a descriptive name to help avoid +collisions. If the library name is namespaced then use '_' as a separator +in the group name. + +For example, the ``oslo.log`` library should use ``oslo_log`` as the +group name. diff --git a/doc/source/reference/opts.rst b/doc/source/reference/opts.rst new file mode 100644 index 0000000..aaf5ead --- /dev/null +++ b/doc/source/reference/opts.rst @@ -0,0 +1,25 @@ +.. _option-definitions: + +------------------ +Option Definitions +------------------ + +.. currentmodule:: oslo_config.cfg + +.. autoclass:: Opt +.. autoclass:: StrOpt +.. autoclass:: BoolOpt +.. autoclass:: IntOpt +.. autoclass:: FloatOpt +.. autoclass:: ListOpt +.. autoclass:: DictOpt +.. autoclass:: MultiOpt +.. autoclass:: MultiStrOpt +.. autoclass:: IPOpt +.. autoclass:: PortOpt +.. autoclass:: HostnameOpt +.. autoclass:: HostAddressOpt +.. autoclass:: URIOpt +.. autoclass:: DeprecatedOpt +.. autoclass:: SubCommandOpt +.. autoclass:: OptGroup diff --git a/doc/source/reference/parser.rst b/doc/source/reference/parser.rst new file mode 100644 index 0000000..64b8b38 --- /dev/null +++ b/doc/source/reference/parser.rst @@ -0,0 +1,11 @@ +------------ +File Parsing +------------ + +.. autoclass:: oslo_config.iniparser.BaseParser + +.. autoclass:: oslo_config.cfg.ConfigParser + :members: parse + +.. autoclass:: oslo_config.cfg.MultiConfigParser + :members: read, get diff --git a/doc/source/reference/sphinxconfiggen.rst b/doc/source/reference/sphinxconfiggen.rst new file mode 100644 index 0000000..5768d73 --- /dev/null +++ b/doc/source/reference/sphinxconfiggen.rst @@ -0,0 +1,50 @@ +==================================== +Sphinx Oslo Sample Config Generation +==================================== + +Included with oslo.config is a sphinx extension to generate a sample config +file at the beginning of each sphinx build. To activate the extension add +``oslo_config.sphinxconfiggen`` to the list of extensions in your sphinx +``conf.py``. + +Then you just need to use the ``config_generator_config_file`` option to point +the config generator at the config file which tells it how to generate the +sample config. If one isn't specified or it doesn't point to a real file the +sample config file generation will be skipped. + +To generate multiple files, set ``config_generator_config_file`` to a +list of tuples containing the input filename and the base name for the +output file. + +The output value can be ``None``, in which case the name is taken from +the input value. + +The input name can be an full path or a value relative to the +documentation source directory. + +For example:: + + config_generator_config_file = [ + ('../../etc/glance-api.conf', 'api'), + ('../../etc/glance-cache.conf', 'cache'), + ('../../etc/glance-glare.conf', None), + ('../../etc/glance-registry.conf', None), + ('../../etc/glance-scrubber.conf', None), + ] + +Produces the output files ``api.conf.sample``, ``cache.conf.sample``, +``glance-glare.conf.sample``, ``glance-registry.conf.sample``, and +``glance-scrubber.conf.sample``. + +Output File Name +---------------- + +By default the sphinx plugin will generate the sample config file and +name the file ``sample.config``. However, if for whatever reason you'd +like the name to be more specific to the project name you can use the +``sample_config_basename`` config option to specify the project +name. If it's set the output filename will be that value with a +``.conf.sample`` extension. For example if you set the value to +"``nova``" the output filename will be "``nova.conf.sample``". You can +also include a subdirectory off of the documentation source directory +as part of this value. diff --git a/doc/source/reference/sphinxext.rst b/doc/source/reference/sphinxext.rst new file mode 100644 index 0000000..5e9a1a5 --- /dev/null +++ b/doc/source/reference/sphinxext.rst @@ -0,0 +1,60 @@ +==================== + Sphinx Integration +==================== + +The ``oslo_config.sphinxext`` module defines a custom domain for +documenting configuration options. The domain includes a directive and +two roles. + +.. rst:directive:: show-options + + Given a list of namespaces, show all of the options exported from + them. + + :: + + .. show-options:: + + oslo.config + oslo.log + + To show each namespace separately, add the ``split-namespaces`` + flag. + + :: + + .. show-options:: + :split-namespaces: + + oslo.config + oslo.log + + To use an existing configuration file for the sample configuration + generator, use the ``config-file`` option instead of specifying the + namespaces inline. + :: + + .. show-options:: + :config-file: etc/oslo-config-generator/glance-api.conf + +.. rst:role:: option + + Link to an option. + + :: + + #. :oslo.config:option:`config_file` + #. :oslo.config:option:`DEFAULT.config_file` + + #. :oslo.config:option:`config_file` + #. :oslo.config:option:`DEFAULT.config_file` + +.. rst:role:: group + + Link to an option group. + + :: + + :oslo.config:group:`DEFAULT` + + :oslo.config:group:`DEFAULT` diff --git a/doc/source/reference/styleguide.rst b/doc/source/reference/styleguide.rst new file mode 100644 index 0000000..d290ce3 --- /dev/null +++ b/doc/source/reference/styleguide.rst @@ -0,0 +1,84 @@ +---------------------------- +Style Guide for Help Strings +---------------------------- + +This document provides style guidance for writing the required help +strings for configuration options using the ``oslo.config`` code. + +The help strings are parsed from the code to appear in sample +configuration files, such as ``etc/cinder/cinder.conf`` in the +cinder repository. They are also displayed in the `OpenStack +Configuration Reference +<http://docs.openstack.org/draft/config-reference/index.html>`_. + +Examples:: + + cfg.StrOpt('bind_host', + default='0.0.0.0', + help='IP address to listen on.'), + cfg.PortOpt('bind_port', + default=9292, + help='Port number to listen on.') + + +Style Guide +----------- + +1. Use sentence-style capitalization for help strings: Capitalize or + uppercase the first character (see the examples above). + +2. Only use single spaces, no double spaces. + +3. Properly capitalize words. If in doubt check the `OpenStack Glossary <http://docs.openstack.org/user-guide/common/glossary.html>`_. + +4. End each segment with a period and write complete sentences if + possible. Examples:: + + cfg.StrOpt('osapi_volume_base_URL', + default=None, + help='Base URL that appears in links to the OpenStack ' + 'Block Storage API.') + + + cfg.StrOpt('host', + default=socket.gethostname(), + help='Name of this node. This can be an opaque identifier. ' + 'It is not necessarily a host name, FQDN, or IP address.') + +5. Use valid service names and API names. Valid service names include + nova, cinder, swift, glance, heat, neutron, trove, ceilometer, + horizon, keystone, and marconi. + + Valid API names include Compute API, Image Service API, Identity + Service API, Object Storage API, Block Storage API, Database API, + and Networking API. + +Format +------ + +1. For multi-line strings, remember that strings are concatenated + directly and thus spaces need to be inserted normally. + + This document recommends to add the space at the end of a line and + not at the beginning. Example:: + + cfg.BoolOpt('glance_api_ssl_compression', + default=False, + help='Enables or disables negotiation of SSL layer ' + 'compression. In some cases disabling compression ' + 'can improve data throughput, such as when high ' + 'network bandwidth is available and you use ' + 'compressed image formats like qcow2.') + +2. It is possible to preformat the multi-line strings to increase readability. + Line break characters ``\n`` will be kept as they are used in the help text. + Example:: + + cfg.IntOpt('sync_power_state_interval', + default=600, + help='Interval to sync power states between the database and ' + 'the hypervisor.\n' + '\n' + '-1: disables the sync \n' + ' 0: run at the default rate.\n' + '>0: the interval in seconds') diff --git a/doc/source/reference/types.rst b/doc/source/reference/types.rst new file mode 100644 index 0000000..9f7ea13 --- /dev/null +++ b/doc/source/reference/types.rst @@ -0,0 +1,6 @@ +--------------------------- +Option Types and Validation +--------------------------- + +.. automodule:: oslo_config.types + :members: |