From 1f17b823e0fbe082db74f1707af3888cacc6a3e4 Mon Sep 17 00:00:00 2001
From: Ben Nemec <bnemec@redhat.com>
Date: Wed, 12 Sep 2018 21:16:22 +0000
Subject: [PATCH] Add release note and documentation for config validator

Change-Id: Id23d7bbb38c6780621f09b2e24c0cc88831bdb1a
---
 doc/source/cli/index.rst                      |  1 +
 doc/source/cli/validator.rst                  | 63 +++++++++++++++++++
 .../config-validator-256817f2183994fd.yaml    |  9 +++
 3 files changed, 73 insertions(+)
 create mode 100644 doc/source/cli/validator.rst
 create mode 100644 releasenotes/notes/config-validator-256817f2183994fd.yaml

diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
index b81f89f8..dbe19492 100644
--- a/doc/source/cli/index.rst
+++ b/doc/source/cli/index.rst
@@ -6,4 +6,5 @@
    :maxdepth: 2
 
    generator
+   validator
 
diff --git a/doc/source/cli/validator.rst b/doc/source/cli/validator.rst
new file mode 100644
index 00000000..637aeeb5
--- /dev/null
+++ b/doc/source/cli/validator.rst
@@ -0,0 +1,63 @@
+=====================
+oslo-config-validator
+=====================
+
+`oslo-config-validator` is a utility for verifying that the entries in a
+config file are correct. It will report an error for any options found that
+are not defined by the service, and a warning for any deprecated options found.
+
+.. versionadded:: 6.5.0
+
+Usage
+-----
+
+There are two primary ways to use the config validator. It can use the sample
+config generator configuration file found in each service to determine the list
+of available options, or it can consume a machine-readable sample config that
+provides the same information.
+
+Sample Config Generator Configuration
+-------------------------------------
+
+.. note:: When using this method, all dependencies of the service must be
+          installed in the environment where the validator is run.
+
+There are two parameters that must be passed to the validator in this case:
+``--config-file`` and ``--input-file``.  ``--config-file`` should point at the
+location of the sample config generator configuration file, while
+``--input-file`` should point at the location of the configuration file to be
+validated.
+
+Here's an example of using the validator on Nova as installed by Devstack::
+
+    $ oslo-config-validator --config-file /opt/stack/nova/etc/nova/nova-config-generator.conf --input-file /etc/nova/nova.conf
+    ERROR:root:keystone_authtoken/user_domain_name not found
+    ERROR:root:keystone_authtoken/password not found
+    ERROR:root:keystone_authtoken/project_domain_name not found
+    ERROR:root:keystone_authtoken/project_name not found
+    ERROR:root:keystone_authtoken/username not found
+    ERROR:root:keystone_authtoken/auth_url not found
+
+Machine-Readable Sample Config
+------------------------------
+
+.. note:: For most accurate results, the machine-readable sample config should
+          be generated from the same version of the code as is running on
+          the system whose config file is being validated.
+
+In this case, a machine-readable sample config must first be generated, as
+described in :doc:`generator`.
+
+This file is then passed to the validator with ``--opt-data``, along with the
+config file to validated in ``--input-file`` as above.
+
+Here's an example of using the validator on Nova as installed by Devstack, with
+a sample config file ``config-data.yaml`` created by the config generator::
+
+    $ oslo-config-validator --opt-data config-data.yaml --input-file /etc/nova/nova.conf
+    ERROR:root:keystone_authtoken/username not found
+    ERROR:root:keystone_authtoken/project_domain_name not found
+    ERROR:root:keystone_authtoken/user_domain_name not found
+    ERROR:root:keystone_authtoken/project_name not found
+    ERROR:root:keystone_authtoken/password not found
+    ERROR:root:keystone_authtoken/auth_url not found
diff --git a/releasenotes/notes/config-validator-256817f2183994fd.yaml b/releasenotes/notes/config-validator-256817f2183994fd.yaml
new file mode 100644
index 00000000..0b9ff24a
--- /dev/null
+++ b/releasenotes/notes/config-validator-256817f2183994fd.yaml
@@ -0,0 +1,9 @@
+---
+features:
+  - |
+    A validator for config files is now available. When run against a config
+    file, it will report an error for any options present that aren't defined
+    in the service and will report a warning for any deprecated options in
+    the file. In order to discover the available options for a service, it
+    can either use the sample config generator configuration file or a
+    machine-readable sample config generated elsewhere.