d768fbc97d
This change adds a module for listing configuration options and setting their defaults. It also changes the key manager base class to incorporate a configuration during creation. By default, the key manager will continue to use the global CONF object from the oslo.config package. For the most part, this change will be backwards compatible. The one exception is the creation of sample configuration files. Previously, importing castellan was sufficient to add these options to the global configuration object. Now, these options will need to be applied by using the castellan.options.list_opts function, or adding them through other means, to create sample configuration files. Similar applies for setting configuration before instantiating a key manager. changes * adding castellan.options with list_opts and set_defaults functions * changing KeyManager abc to include a configuration option to __init__ * changing barbican and not_implemented key managers to accept configuration parameters * adding tests for set_defaults function * fixing barbican tests to accomodate new configuration parameter * adding documentation about configuration usage * adding castellan configs to oslo entry point in setup.cfg * adding a genconfig target to tox for producing a sample castellan configuration file * adding the sample configuration file to the git ignore * renaming barbican option api_version to barbican_api_version Change-Id: I86d6d7d49a893beaae6f311060ec593e0482d889 Implements: blueprint improved-configuration-options
107 lines
3.1 KiB
ReStructuredText
107 lines
3.1 KiB
ReStructuredText
========
|
|
Usage
|
|
========
|
|
|
|
To use castellan in a project::
|
|
|
|
import castellan
|
|
|
|
|
|
Configuring castellan
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Castellan contains several options which control the key management
|
|
service usage and the configuration of that service. It also contains
|
|
functions to help configure the defaults and produce listings for use
|
|
with the ``oslo-config-generator`` application.
|
|
|
|
In general, castellan configuration is handled by passing an
|
|
``oslo_config.cfg.ConfigOpts`` object into the
|
|
``castellan.key_manager.API`` call when creating your key manager. By
|
|
default, when no ``ConfigOpts`` object is provided, the key manager will
|
|
use the global ``oslo_config.cfg.CONF`` object.
|
|
|
|
**Example. Using the global CONF object for configuration.**
|
|
|
|
.. code:: python
|
|
|
|
from castellan import key_manager
|
|
|
|
manager = key_manager.API()
|
|
|
|
**Example. Using a predetermined configuration object.**
|
|
|
|
.. code:: python
|
|
|
|
from oslo_config import cfg
|
|
from castellan import key_manager
|
|
|
|
conf = cfg.ConfigOpts()
|
|
manager = key_manager.API(configuration=conf)
|
|
|
|
Controlling default options
|
|
---------------------------
|
|
|
|
To change the default behavior of castellan, and the key management service
|
|
it uses, the ``castellan.options`` module provides the ``set_defaults``
|
|
function. This function can be used at run-time to change the behavior of
|
|
the library or the key management service provider.
|
|
|
|
**Example. Changing the barbican endpoint.**
|
|
|
|
.. code:: python
|
|
|
|
from oslo_config import cfg
|
|
from castellan import options
|
|
from castellan import key_manager
|
|
|
|
conf = cfg.ConfigOpts()
|
|
options.set_defaults(conf, barbican_endpoint='http://192.168.0.1:9311/')
|
|
manager = key_manager.API(conf)
|
|
|
|
**Example. Changing the key manager provider while using the global
|
|
configuration.**
|
|
|
|
.. code:: python
|
|
|
|
from oslo_config import cfg
|
|
from castellan import options
|
|
from castellan import key_manager
|
|
|
|
options.set_defaults(cfg.CONF, api_class='some.other.KeyManager')
|
|
manager = key_manager.API()
|
|
|
|
Generating sample configuration files
|
|
-------------------------------------
|
|
|
|
Castellan includes a tox configuration for creating a sample configuration
|
|
file. This file will contain only the values that will be used by
|
|
castellan. To produce this file, run the following command from the
|
|
root of the castellan project directory:
|
|
|
|
.. code:: console
|
|
|
|
$ tox -e genconfig
|
|
|
|
Adding castellan to configuration files
|
|
---------------------------------------
|
|
|
|
One common task for OpenStack projects is to create project configuration
|
|
files. Castellan provides a ``list_opts`` function in the
|
|
``castellan.options`` module to aid in generating these files when using
|
|
the ``oslo-config-generator``. This function can be specified in the
|
|
:file:`setup.cfg` file of your project to inform oslo of the
|
|
configuration options. *Note, this will use the default values supplied
|
|
by the castellan package.*
|
|
|
|
**Example. Adding castellan to the oslo.config entry point.**
|
|
|
|
.. code:: ini
|
|
|
|
[entry_points]
|
|
oslo.config.opts =
|
|
castellan.config = castellan.options:list_opts
|
|
|
|
For more information on the oslo configuration generator, please see
|
|
http://docs.openstack.org/developer/oslo.config/generator.html
|