Expand and clean up documentation for the config generator
Add some section headings, clean up some of the formatting, and add information about how to handle modules with optional dependencies. Change-Id: I731fd7b191e834e22a99516f1b4b584bad6868fd
This commit is contained in:
Doug Hellmann
parent
5379261c78
commit
7da430b9f4
@ -1,8 +1,117 @@
|
||||
---------------------
|
||||
oslo-config-generator
|
||||
=======================
|
||||
oslo-config-generator
|
||||
=======================
|
||||
|
||||
oslo-config-generator is a utility for generating sample config files. For
|
||||
example, to generate a sample config file for oslo.messaging you would run::
|
||||
|
||||
$> oslo-config-generator --namespace oslo.messaging > oslo.messaging.conf
|
||||
|
||||
This generated sample lists all of the available options, along with their help
|
||||
string, type, deprecated aliases and defaults.
|
||||
|
||||
To generate a sample config file for an application ``myapp`` that has
|
||||
its own options and uses oslo.messaging, you can list both
|
||||
namespaces::
|
||||
|
||||
$> oslo-config-generator --namespace myapp --namespace oslo.messaging > myapp.conf
|
||||
|
||||
Defining Option Discovery Entry Points
|
||||
--------------------------------------
|
||||
|
||||
The ``--namespace`` option specifies an entry point name registered under the
|
||||
'oslo.config.opts' entry point namespace. For example, in oslo.messaging's
|
||||
setup.cfg we have::
|
||||
|
||||
[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_name, [opt_1, opt_2]) tuples. For example::
|
||||
|
||||
opts = [
|
||||
cfg.StrOpt('foo'),
|
||||
cfg.StrOpt('bar'),
|
||||
]
|
||||
|
||||
cfg.CONF.register_opts(opts, group='blaa')
|
||||
|
||||
def list_opts():
|
||||
return [('blaa', opts)]
|
||||
|
||||
You might choose to return a copy of the options so that the return value can't
|
||||
be modified for nefarious purposes, though this is not strictly necessary::
|
||||
|
||||
def list_opts():
|
||||
return [('blaa', copy.deepcopy(opts))]
|
||||
|
||||
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.
|
||||
|
||||
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::
|
||||
|
||||
[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::
|
||||
|
||||
$> 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::
|
||||
|
||||
$> 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
|
||||
---------------------
|
||||
|
||||
.. automodule:: oslo_config.generator
|
||||
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::
|
||||
|
||||
cfg.StrOpt('base_dir'
|
||||
default=os.getcwd(),
|
||||
sample_default='/usr/lib/myapp')
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
.. currentmodule:: oslo_config.generator
|
||||
|
||||
|
||||
@ -15,92 +15,11 @@
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
r"""
|
||||
A sample configuration file generator.
|
||||
"""Sample configuration generator
|
||||
|
||||
oslo-config-generator is a utility for generating sample config files. For
|
||||
example, to generate a sample config file for oslo.messaging you would run::
|
||||
Tool for generating a sample configuration file. See
|
||||
../doc/source/generator.rst for details.
|
||||
|
||||
$> oslo-config-generator --namespace oslo.messaging > oslo.messaging.conf
|
||||
|
||||
This generated sample lists all of the available options, along with their help
|
||||
string, type, deprecated aliases and defaults.
|
||||
|
||||
The --namespace option specifies an entry point name registered under the
|
||||
'oslo.config.opts' entry point namespace. For example, in oslo.messaging's
|
||||
setup.cfg we have::
|
||||
|
||||
[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_name, [opt_1, opt_2]) tuples. For example::
|
||||
|
||||
opts = [
|
||||
cfg.StrOpt('foo'),
|
||||
cfg.StrOpt('bar'),
|
||||
]
|
||||
|
||||
cfg.CONF.register_opts(opts, group='blaa')
|
||||
|
||||
def list_opts():
|
||||
return [('blaa', opts)]
|
||||
|
||||
You might choose to return a copy of the options so that the return value can't
|
||||
be modified for nefarious purposes::
|
||||
|
||||
def list_opts():
|
||||
return [('blaa', copy.deepcopy(opts))]
|
||||
|
||||
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::
|
||||
|
||||
[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::
|
||||
|
||||
$> 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::
|
||||
|
||||
$> 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
|
||||
|
||||
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::
|
||||
|
||||
cfg.StrOpt('base_dir'
|
||||
default=os.getcwd(),
|
||||
sample_default='/usr/lib/myapp')
|
||||
"""
|
||||
|
||||
import logging
|
||||
|
||||
Loading…
Reference in New Issue
Block a user