diff --git a/doc/source/generator.rst b/doc/source/generator.rst index 55bff32..a42882b 100644 --- a/doc/source/generator.rst +++ b/doc/source/generator.rst @@ -2,61 +2,136 @@ 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` 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``). - $> oslo-config-generator --namespace oslo.messaging > oslo.messaging.conf +.. versionadded:: 1.4.0 -This generated sample lists all of the available options, along with their help -string, type, deprecated aliases and defaults. +.. versionchanged:: 4.3.0 -To generate a sample config file for an application ``myapp`` that has -its own options and uses oslo.messaging, you can list both -namespaces:: + The :option:`oslo-config-generator --format` parameter was added, which + allows outputting in additional formats. - $> oslo-config-generator --namespace myapp --namespace oslo.messaging > myapp.conf +Usage +----- -.. versionadded:: 1.4 +.. program:: oslo-config-generator + +.. code-block:: shell + + oslo-config-generator + --namespace [--namespace ...] + [--output-file ] + [--wrap-width ] + [--format ] + [--minimal] + [--summarize] + +.. option:: --namespace + + Option namespace under ``oslo.config.opts`` in which to query for options. + +.. option:: --output-file + + Path of the file to write to. + + :Default: stdout + +.. option:: --wrap-width + + The maximum length of help lines. + + :Default: 70 + +.. option:: --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 ``--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:: +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:: +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: - opts1 = [ - cfg.StrOpt('foo'), - cfg.StrOpt('bar'), - ] +.. code-block:: python - opts2 = [ - cfg.StrOpt('baz'), - ] + from oslo_config import cfg - baz_group = cfg.OptGroup(name='baz_group' - title='Baz group options', - help='Baz group help text') - cfg.CONF.register_group(baz_group) + opts1 = [ + cfg.StrOpt('foo'), + cfg.StrOpt('bar'), + ] - cfg.CONF.register_opts(opts1, group='blaa') - cfg.CONF.register_opts(opts2, group=baz_group) + opts2 = [ + cfg.StrOpt('baz'), + ] - 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)] + 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:: @@ -89,11 +164,11 @@ 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 + [entry_points] + oslo.config.opts.defaults = + keystone = keystone.common.config:update_opt_defaults .. warning:: @@ -121,7 +196,7 @@ 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 @@ -130,12 +205,105 @@ its normal startup process. 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 + :doc:`opts`. + +``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:: +register multiple entry points: + +.. code-block:: ini [entry_points] oslo.config.opts = @@ -145,32 +313,36 @@ register multiple entry points:: and generate a config file specific to each program:: - $> oslo-config-generator --namespace oslo.messaging \ +.. code-block:: shell + + $ oslo-config-generator --namespace oslo.messaging \ --namespace nova.common \ --namespace nova.api > nova-api.conf - $> oslo-config-generator --namespace oslo.messaging \ + $ 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:: +files: - $> cat > config-generator/api.conf < cat > config-generator/compute.conf < oslo-config-generator --config-file config-generator/api.conf - $> oslo-config-generator --config-file config-generator/compute.conf +.. code-block:: shell + + $ cat > config-generator/api.conf < config-generator/compute.conf <