2610dff995
Rather than have the API docs hand-curated and scattered throughout the documentation, let's use the apidoc module like all of the other Oslo projects so our API docs are consistent and easy to find. The documents that were exclusively API docs are removed entirely, and the ones where API docs were included with other content have been changed to reference the generated API docs rather than include them inline. The one exception is the drivers because they are in private modules that don't show up in the API docs. Those are still explicitly documented. Change-Id: I00bdd963e0d4f270c0d4b50c05f420317a137fd5
361 lines
12 KiB
ReStructuredText
361 lines
12 KiB
ReStructuredText
=======================
|
|
oslo-config-generator
|
|
=======================
|
|
|
|
`oslo-config-generator` is a utility for generating sample config files in a
|
|
variety of formats. Sample config files list all of the available options,
|
|
along with their help string, type, deprecated aliases and defaults. These
|
|
sample files can be used as config files for `oslo.config` itself (``ini``) or
|
|
by configuration management tools (``json``, ``yaml``).
|
|
|
|
.. versionadded:: 1.4.0
|
|
|
|
.. versionchanged:: 4.3.0
|
|
|
|
The :option:`oslo-config-generator --format` parameter was added, which
|
|
allows outputting in additional formats.
|
|
|
|
Usage
|
|
-----
|
|
|
|
.. program:: oslo-config-generator
|
|
|
|
.. code-block:: shell
|
|
|
|
oslo-config-generator
|
|
--namespace <namespace> [--namespace <namespace> ...]
|
|
[--output-file <output-file>]
|
|
[--wrap-width <wrap-width>]
|
|
[--format <format>]
|
|
[--minimal]
|
|
[--summarize]
|
|
|
|
.. option:: --namespace <namespace>
|
|
|
|
Option namespace under ``oslo.config.opts`` in which to query for options.
|
|
|
|
.. option:: --output-file <output-file>
|
|
|
|
Path of the file to write to.
|
|
|
|
:Default: stdout
|
|
|
|
.. option:: --wrap-width <wrap-width>
|
|
|
|
The maximum length of help lines.
|
|
|
|
:Default: 70
|
|
|
|
.. option:: --format <format>
|
|
|
|
Desired format for the output. ``ini`` is the only format that can be used
|
|
directly with `oslo.config`. ``json`` and ``yaml`` are intended for
|
|
third-party tools that want to write config files based on the sample config
|
|
data. For more information, refer to :ref:`machine-readable-configs`.
|
|
|
|
:Choices: ini, json, yaml
|
|
|
|
.. option:: --minimal
|
|
|
|
Generate a minimal required configuration.
|
|
|
|
.. option:: --summarize
|
|
|
|
Only output summaries of help text to config files. Retain longer help text
|
|
for Sphinx documents.
|
|
|
|
For example, to generate a sample config file for `oslo.messaging` you would
|
|
run:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ oslo-config-generator --namespace oslo.messaging > oslo.messaging.conf
|
|
|
|
To generate a sample config file for an application ``myapp`` that has its own
|
|
options and uses `oslo.messaging`, you would list both namespaces:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ oslo-config-generator --namespace myapp \
|
|
--namespace oslo.messaging > myapp.conf
|
|
|
|
To generate a sample config file for `oslo.messaging` in `JSON` format, you
|
|
would run:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ oslo-config-generator --namespace oslo.messaging \
|
|
--format json > oslo.messaging.conf
|
|
|
|
Defining Option Discovery Entry Points
|
|
--------------------------------------
|
|
|
|
The :option:`oslo-config-generator --namespace` option specifies an entry point
|
|
name registered under the ``oslo.config.opts`` entry point namespace. For
|
|
example, in the `oslo.messaging` ``setup.cfg`` we have:
|
|
|
|
.. code-block:: ini
|
|
|
|
[entry_points]
|
|
oslo.config.opts =
|
|
oslo.messaging = oslo.messaging.opts:list_opts
|
|
|
|
The callable referenced by the entry point should take no arguments and return
|
|
a list of ``(group, [opt_1, opt_2])`` tuples, where ``group`` is either a group
|
|
name as a string or an ``OptGroup`` object. Passing the ``OptGroup`` object
|
|
allows the consumer of the ``list_opts`` method to access and publish group
|
|
help. An example, using both styles:
|
|
|
|
.. code-block:: python
|
|
|
|
from oslo_config import cfg
|
|
|
|
opts1 = [
|
|
cfg.StrOpt('foo'),
|
|
cfg.StrOpt('bar'),
|
|
]
|
|
|
|
opts2 = [
|
|
cfg.StrOpt('baz'),
|
|
]
|
|
|
|
baz_group = cfg.OptGroup(name='baz_group'
|
|
title='Baz group options',
|
|
help='Baz group help text')
|
|
cfg.CONF.register_group(baz_group)
|
|
|
|
cfg.CONF.register_opts(opts1, group='blaa')
|
|
cfg.CONF.register_opts(opts2, group=baz_group)
|
|
|
|
def list_opts():
|
|
# Allows the generation of the help text for
|
|
# the baz_group OptGroup object. No help
|
|
# text is generated for the 'blaa' group.
|
|
return [('blaa', opts1), (baz_group, opts2)]
|
|
|
|
.. note::
|
|
|
|
You should return the original options, not a copy, because the
|
|
default update hooks depend on the original option object being
|
|
returned.
|
|
|
|
The module holding the entry point *must* be importable, even if the
|
|
dependencies of that module are not installed. For example, driver
|
|
modules that define options but have optional dependencies on
|
|
third-party modules must still be importable if those modules are not
|
|
installed. To accomplish this, the optional dependency can either be
|
|
imported using :func:`oslo.utils.importutils.try_import` or the option
|
|
definitions can be placed in a file that does not try to import the
|
|
optional dependency.
|
|
|
|
Modifying Defaults from Other Namespaces
|
|
----------------------------------------
|
|
|
|
Occasionally applications need to override the defaults for options
|
|
defined in libraries. At runtime this is done using an API within the
|
|
library. Since the config generator cannot guarantee the order in
|
|
which namespaces will be imported, we can't ensure that application
|
|
code can change the option defaults before the generator loads the
|
|
options from a library. Instead, a separate optional processing hook
|
|
is provided for applications to register a function to update default
|
|
values after *all* options are loaded.
|
|
|
|
The hooks are registered in a separate entry point namespace
|
|
(``oslo.config.opts.defaults``), using the same entry point name as
|
|
**the application's** ``list_opts()`` function.
|
|
|
|
.. code-block:: ini
|
|
|
|
[entry_points]
|
|
oslo.config.opts.defaults =
|
|
keystone = keystone.common.config:update_opt_defaults
|
|
|
|
.. warning::
|
|
|
|
Never, under any circumstances, register an entry point using a
|
|
name owned by another project. Doing so causes unexpected interplay
|
|
between projects within the config generator and will result in
|
|
failure to generate the configuration file or invalid values
|
|
showing in the sample.
|
|
|
|
In this case, the name of the entry point for the default override
|
|
function *must* match the name of one of the entry points defining
|
|
options for the application in order to be detected and
|
|
used. Applications that have multiple list_opts functions should use
|
|
one that is present in the inputs for the config generator where
|
|
the changed defaults need to appear. For example, if an application
|
|
defines ``foo.api`` to list the API-related options, and needs to
|
|
override the defaults in the ``oslo.middleware.cors`` library, the
|
|
application should register ``foo.api`` under
|
|
``oslo.config.opts.defaults`` and point to a function within the
|
|
application code space that changes the defaults for
|
|
``oslo.middleware.cors``.
|
|
|
|
The update function should take no arguments. It should invoke the
|
|
public :func:`set_defaults` functions in any libraries for which it
|
|
has option defaults to override, just as the application does during
|
|
its normal startup process.
|
|
|
|
.. code-block:: python
|
|
|
|
from oslo_log import log
|
|
|
|
def update_opt_defaults():
|
|
log.set_defaults(
|
|
default_log_levels=log.get_default_log_levels() + ['noisy=WARN'],
|
|
)
|
|
|
|
.. _machine-readable-configs:
|
|
|
|
Generating Machine Readable Configs
|
|
-----------------------------------
|
|
|
|
All deployment tools have to solve a similar problem: how to generate the
|
|
config files for each service at deployment time. To help with this problem,
|
|
`oslo-config-generator` can generate machine-readable sample config files that
|
|
output the same data as the INI files used by `oslo.config` itself, but in a
|
|
YAML or JSON format that can be more easily consumed by deployment tools.
|
|
|
|
.. important::
|
|
|
|
The YAML and JSON-formatted files generated by `oslo-config-generator`
|
|
cannot be used by `oslo.config` itself - they are only for use by other
|
|
tools.
|
|
|
|
For example, some YAML-formatted output might look like so:
|
|
|
|
.. code-block:: yaml
|
|
|
|
generator_options:
|
|
config_dir: []
|
|
config_file: []
|
|
format_: yaml
|
|
minimal: false
|
|
namespace:
|
|
- keystone
|
|
output_file: null
|
|
summarize: false
|
|
wrap_width: 70
|
|
options:
|
|
DEFAULT:
|
|
help: ''
|
|
opts:
|
|
- advanced: false
|
|
choices: []
|
|
default: null
|
|
deprecated_for_removal: false
|
|
deprecated_opts: []
|
|
deprecated_reason: null
|
|
deprecated_since: null
|
|
dest: admin_token
|
|
help: Using this feature is *NOT* recommended. Instead, use the `keystone-manage
|
|
bootstrap` command. The value of this option is treated as a "shared secret"
|
|
that can be used to bootstrap Keystone through the API. This "token" does
|
|
not represent a user (it has no identity), and carries no explicit authorization
|
|
(it effectively bypasses most authorization checks). If set to `None`, the
|
|
value is ignored and the `admin_token` middleware is effectively disabled.
|
|
However, to completely disable `admin_token` in production (highly recommended,
|
|
as it presents a security risk), remove `AdminTokenAuthMiddleware` (the `admin_token_auth`
|
|
filter) from your paste application pipelines (for example, in `keystone-paste.ini`).
|
|
max: null
|
|
metavar: null
|
|
min: null
|
|
mutable: false
|
|
name: admin_token
|
|
namespace: keystone
|
|
positional: false
|
|
required: false
|
|
sample_default: null
|
|
secret: true
|
|
short: null
|
|
type: string value
|
|
- ...
|
|
...
|
|
deprecated_options:
|
|
DEFAULT:
|
|
- name: bind_host
|
|
replacement_group: eventlet_server
|
|
replacement_name: public_bind_host
|
|
|
|
where the top-level keys are:
|
|
|
|
``generator_options``
|
|
|
|
The options passed to the :program:`oslo-config-generator` tool itself
|
|
|
|
``options``
|
|
|
|
All options registered in the provided namespace(s). These are grouped under
|
|
the ``OptGroup`` they are assigned to which defaults to ``DEFAULT`` if unset.
|
|
|
|
For information on the various attributes of each option, refer to
|
|
:class:`oslo_config.cfg.Opt` and its subclasses.
|
|
|
|
``deprecated_options``
|
|
|
|
All **deprecated** options registered in the provided namespace(s). Like
|
|
``options``, these options are grouped by ``OptGroup``.
|
|
|
|
Generating Multiple Sample Configs
|
|
----------------------------------
|
|
|
|
A single codebase might have multiple programs, each of which use a subset of
|
|
the total set of options registered by the codebase. In that case, you can
|
|
register multiple entry points:
|
|
|
|
.. code-block:: ini
|
|
|
|
[entry_points]
|
|
oslo.config.opts =
|
|
nova.common = nova.config:list_common_opts
|
|
nova.api = nova.config:list_api_opts
|
|
nova.compute = nova.config:list_compute_opts
|
|
|
|
and generate a config file specific to each program:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ oslo-config-generator --namespace oslo.messaging \
|
|
--namespace nova.common \
|
|
--namespace nova.api > nova-api.conf
|
|
$ oslo-config-generator --namespace oslo.messaging \
|
|
--namespace nova.common \
|
|
--namespace nova.compute > nova-compute.conf
|
|
|
|
To make this more convenient, you can use config files to describe your config
|
|
files:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ cat > config-generator/api.conf <<EOF
|
|
[DEFAULT]
|
|
output_file = etc/nova/nova-api.conf
|
|
namespace = oslo.messaging
|
|
namespace = nova.common
|
|
namespace = nova.api
|
|
EOF
|
|
$ cat > config-generator/compute.conf <<EOF
|
|
[DEFAULT]
|
|
output_file = etc/nova/nova-compute.conf
|
|
namespace = oslo.messaging
|
|
namespace = nova.common
|
|
namespace = nova.compute
|
|
EOF
|
|
$ oslo-config-generator --config-file config-generator/api.conf
|
|
$ oslo-config-generator --config-file config-generator/compute.conf
|
|
|
|
Sample Default Values
|
|
---------------------
|
|
|
|
The default runtime values of configuration options are not always the most
|
|
suitable values to include in sample config files - for example, rather than
|
|
including the IP address or hostname of the machine where the config file
|
|
was generated, you might want to include something like ``10.0.0.1``. To
|
|
facilitate this, options can be supplied with a ``sample_default`` attribute:
|
|
|
|
.. code-block:: python
|
|
|
|
cfg.StrOpt('base_dir'
|
|
default=os.getcwd(),
|
|
sample_default='/usr/lib/myapp')
|