Merge "Documentation of the config datasource."

doc/source/admin/config-datasource.rst

@@ -0,0 +1,56 @@
+.. _config_datasource:
+
+#####################
+The config datasource
+#####################
+
+Overview
+========
+
+The config datasource is a Congress datasource that let you
+access the definition of configuration options of Openstack
+services on the nodes of the cloud.
+
+Its main purpose is to let administrator check the coherence
+of a deployment by defining constraints on the value of those
+options.
+
+To retrieve the configuration files, the datasource uses an agent that must be configured on the various nodes.
+
+Agent configuration options
+===========================
+
+Please refer to :ref:`config` for the generation of a sample configuration file (``etc/congress-agent.conf.sample``).
+
+The options most important to the agent are described below. They all appear under the ``[agent]`` section of the configuration file.
+
+``host``
+    The name of the host as it will appear in the Congress
+    tables.
+
+``version``
+    This is the Openstack version used on the host. It can be
+    used for rules that only apply to a given version of a service. Standard version names in lowercase should be used (e.g. ``ocata``, ``pike``).
+
+``services``
+    This is a dictionary that associates to each service
+    (use standard service names in lowercase), a description
+    of its configuration file. The description is itself
+    a dictionary. Keys are the paths to the configuration
+    files and values are the path to the template
+    definitions of the configuration files for oslo-config
+    generator.
+
+The agent also requires a valid configuration of the message bus as it uses it to communicate with the datasource driver.
+
+An example of configuration file is the following:
+
+.. code-block:: text
+
+    [DEFAULT]
+    transport_url = rabbit://...
+
+    [cfg_validator]
+    host = compute-node-001
+    version = pike
+    services = nova: { /etc/nova/nova.conf:/opt/stack/nova/etc/nova/nova-config-generator.conf },neutron: { /etc/neutron/neutron.conf:/opt/stack/neutron/etc/oslo-config-generator/neutron.conf },congress: { /etc/congress/congress.conf:/opt/stack/congress/etc/congress-config-generator.conf }

doc/source/admin/deployment.rst

@@ -21,8 +21,8 @@ across nodes.
 
 Section :ref:`config` describes the common configuration options for both
 single-process and multi-process deployments.  After that :ref:`ha_overview`
-and :ref:`ha_deployment` describe how to set up the multi-process deployment.
-
+and :ref:`ha_deployment` describe how to set up the multi-process deployment. Section :ref:`config_datasource`
+describes how to configure agents on the various nodes to use the ``config`` datasource.
 
 .. _config:
 
@@ -106,3 +106,12 @@ HA Deployment
 
    ha-overview
    ha-deployment
+
+---------------------
+The Config Datasource
+---------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   config-datasource

doc/source/conf.py

@@ -97,8 +97,13 @@ latex_documents = [
 
 # -- Options for oslo_config.sphinxconfiggen ---------------------------------
 
-config_generator_config_file = '../../etc/congress-config-generator.conf'
-sample_config_basename = '_static/congress'
+config_generator_config_file = [
+    ('../../etc/congress-config-generator.conf',
+     '_static/congress'),
+    ('../../etc/congress-agent-config-generator.conf',
+     '_static/congress-agent')
+]
+
 
 [extensions]
 todo_include_todos=True

doc/source/configuration/congress-agent.rst

@@ -0,0 +1,6 @@
+===================
+congress-agent.conf
+===================
+
+.. show-options::
+   :config-file: etc/congress-agent-config-generator.conf

doc/source/configuration/samples/congress-agent.rst

@@ -0,0 +1,8 @@
+==========================
+Sample congress-agent.conf
+==========================
+
+This sample configuration can also be viewed in `the raw format
+<../../_static/congress-agent.conf.sample>`_.
+
+.. literalinclude:: ../../_static/congress-agent.conf.sample

doc/source/install/index.rst

@@ -43,6 +43,18 @@ For integrating Congress with DevStack:
 
     $ ./stack.sh
 
+If you want to use the config datasource in a multi-node
+environment, you must configure the Congress agent and
+only the agent on the other nodes. Here is the relevant part
+of ``local.conf``:
+
+.. code-block:: console
+
+    enable_plugin congress https://git.openstack.org/openstack/congress
+    disable_service congress congress-api congress-engine congress-datasources
+    enable_service congress-agent
+
+By default, the datasource is enabled for the nova, neutron and Congress services. To enable it for other services, you can define the variable ``$VALIDATOR_SERVICES``.
 
 Separate install
 --------------------

releasenotes/notes/config-datasource-3017c604d98b29e2.yaml

@@ -0,0 +1,7 @@
+---
+prelude: >
+features:
+  - |
+    Added config datasource driver and its associated agent to import the 
+    contents of service configuration files in Congress. An example of 
+    usage is given in ``examples/cfg_validator``.