Add tripleo-validations user documentation

This describes what the validations are for and how and when to run
them.

Change-Id: I13a52b02a2ae2b3f2c971531e267c3c33ffdac2b

doc/source/basic_deployment/basic_deployment_cli.rst

@@ -293,6 +293,17 @@ as a root device. Please see :ref:`root_device` for details.
 Introspect Nodes
 ----------------
 
+
+.. admonition:: Validations
+
+   Once the undercloud is installed, you can run the
+   ``pre-introspection`` validations::
+
+     openstack workflow execution create tripleo.validations.v1.run_groups '{"group_names": ["pre-introspection"]}'
+
+   Then verify the results as described in :ref:`running_validation_group`.
+
+
 Introspect hardware attributes of nodes::
 
     openstack baremetal introspection bulk start
@@ -341,6 +352,16 @@ subnet. If needed, define the nameserver to be used for the environment::
 Deploy the Overcloud
 --------------------
 
+.. admonition:: Validations
+
+   Before you start the deployment, you may want to run the
+   ``pre-deployment`` validations::
+
+     openstack workflow execution create tripleo.validations.v1.run_groups '{"group_names": ["pre-deployment"]}'
+
+   Then verify the results as described in :ref:`running_validation_group`.
+
+
 By default 1 compute and 1 control node will be deployed, with networking
 configured for the virtual environment.  To customize this, see the output of::
 
@@ -417,6 +438,15 @@ follow :doc:`../advanced_deployment/high_availability`.
 Post-Deployment
 ---------------
 
+.. admonition:: Validations
+
+  After the deployment finished, you can run the ``post-deployment``
+  validations::
+
+    openstack workflow execution create tripleo.validations.v1.run_groups '{"group_names": ["post-deployment"]}'
+
+  Then verify the results as described in :ref:`running_validation_group`.
+
 
 Access the Overcloud
 ^^^^^^^^^^^^^^^^^^^^

doc/source/environments/baremetal.rst

@@ -121,6 +121,34 @@ Setting Up The Undercloud Machine
 
 .. _Red Hat Satellite User Guide: https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/
 
+
+Validations
+^^^^^^^^^^^
+
+You can run the ``prep`` validations to verify the hardware. Later in
+the process, the validations will be run by the undercloud processes.
+
+However, the undercloud is not set up yet. You can install Ansible on
+your local machine (that has SSH connectivity to the undercloud) and
+validate the undercloud from there.
+
+You need Ansible version 2 and the hostname/IP address of the
+undercloud (referred to ``$UNDERCLOUD_HOST`` here)::
+
+  $ sudo yum install ansible
+  $ git clone https://git.openstack.org/openstack/tripleo-validations
+  $ cd tripleo-validations
+  $ printf "[undercloud]\n$UNDERCLOUD_HOST" > hosts
+
+Then get the ``prep`` validations::
+
+  $ grep -l '^\s\+-\s\+prep' -r validations
+
+And run them one by one::
+
+  $ ansible-playbook -i hosts validations/validation-name.yaml
+
+
 Configuration Files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/source/index.rst

@@ -18,6 +18,7 @@ Contents:
    advanced_deployment/backends
    advanced_deployment/custom
    troubleshooting/troubleshooting
+   validations/validations
    mistral-api/mistral-api
    developer/developer
    contributions/contributions
@@ -102,5 +103,9 @@ Linux (RHEL). These steps are marked as follows:
 
    Step that should only be run when deploying with SSL and a self-signed certificate.
 
+.. admonition:: Validations
+
+   Steps that will run the pre and post-deployment validations
+
 Any such steps should *not* be run if the target environment does not match
 the section marking.

doc/source/installation/installing.rst

@@ -96,6 +96,13 @@ Installing the Undercloud
 
      To deploy an undercloud with SSL, see :doc:`../advanced_deployment/ssl`.
 
+  .. admonition:: Validations
+
+     :doc:`../validations/validations` will be installed and
+     configured during undercloud installation. You can set
+     ``enable_validations = false`` in ``undercloud.conf`` to prevent
+     that.
+
 
   Install the undercloud::
 

doc/source/introduction/components.rst

@@ -410,6 +410,19 @@ TripleO UI is the web interface for TripleO.
 * Bugs: https://bugs.launchpad.net/tripleo-ui
 * Blueprints: https://blueprints.launchpad.net/tripleo-ui
 
+tripleo-validations
+-------------------
+
+Pre and post-deployment validations for the deployment workflow.
+
+**Useful links**
+
+* Upstream Project: http://git.openstack.org/cgit/openstack/tripleo-validations/
+* Bugs: https://bugs.launchpad.net/tripleo/+bugs?field.tag=validations
+* Documentation for individual validations: http://docs.openstack.org/developer/tripleo-validations/readme.html#existing-validations
+
+.. note:: When reporting an issue, make sure you add the
+          ``validations`` tag.
 
 Deprecated
 ----------

doc/source/validations/validations.rst

@@ -0,0 +1,108 @@
+Validations
+===========
+
+Since the Newton release, TripleO ships with extensible checks for
+verifying the undercloud configuration, hardware setup, and the
+deployment to find common issues early.
+
+The TripleO GUI runs the validations automatically. While work is
+underway for having them in the command line workflow, too, they need
+to be run by calling a Mistral workflow currently.
+
+The validations are assigned into various groups that indicate when in
+the deployment workflow are they expected to run:
+
+* **prep** validations check the hardware configuration of the
+  undercloud node and should be run before ``openstack undercloud
+  install``.
+
+* **pre-introspection** should be run before we introspect nodes using
+  Ironic Inspector.
+
+* **pre-deployment** validations should be executed before ``openstack
+  overcloud deploy``
+
+* **post-deployment** should be run after the overcloud deployment has
+  finished.
+
+Note that for most of these validations, a failure does not mean that
+you'll be unable to deploy or run OpenStack. But it can indicate
+potential issues with long-term or production setups. If you're
+running an environment for developing or testing TripleO, it's okay
+that some validations fail. In a production setup they should not.
+
+The list of all existing validations and their groups is on the
+`tripleo-validations documentation page`_.
+
+
+
+Running a single validation
+---------------------------
+
+If you want to run one validation in particular (because you're trying
+things out or want to see whether you fixed the failure), you can run
+it like so::
+
+   $ source stackrc
+   $ openstack workflow execution create tripleo.validations.v1.run_validation '{"validation_name": "undercloud-ram"}'
+
+This will run the "undercloud-ram.yaml" validation. All validations
+are stored in the
+``/usr/share/openstack-tripleo-validations/validations/`` directory,
+so to get the name of the validation (``undercloud-ram`` here) find
+the right one there and use its filename without an extension.
+
+The command will return an execution ID, which you can query for the
+results. To find out whether the validation finished, run::
+
+  $ openstack workflow execution show ID
+
+Note the ``State`` value: it can be either ``RUNNING`` or ``SUCCESS``.
+Note that success here only means that the validation finished, not
+that it succeeded. To find that out, we need to read its output::
+
+  $ mistral execution-get-output ID | jq .stdout -r
+
+.. note:: There is an ``openstack workflow execution show output``
+          command which should do the same thing, but it currently
+          doesn't work in all environments supported by |project|.
+
+This will return the hosts the validation ran against, any warnings
+and error messages it encountered along the way as well as an overall
+summary.
+
+
+.. _running_validation_group:
+
+Running a group of validations
+------------------------------
+
+The deployment documentation highlights places where you can run a
+specific group of validations. Here's how to run the
+``pre-deployment`` validations::
+
+  $ source stackrc
+  $ openstack workflow execution create tripleo.validations.v1.run_groups '{"group_names": ["pre-deployment"]}'
+
+Unfortunately, getting the results of all these validations is more
+complicated than in the case a single one. You need to see the tasks
+the workflow above generated and see their results one by one: ::
+
+  $ openstack task execution list
+
+Look for tasks with the ``run_validation`` name. Then take the ID of
+each of those and run::
+
+  $ mistral task-get-result ID | jq .stdout -r
+
+.. note:: There is a ``task execution show result`` command that
+          should do the same thing, but it's not working on all
+          platforms supported by |project|.
+
+Since this can be tedious and hard to script, you can get the list of
+validations belonging to a group instead and run them one-by-one using
+the method above::
+
+  $ openstack action execution run tripleo.validations.list_validations '{"groups": ["pre-deployment"]}' | jq ".result[] | .id"
+
+.. _tripleo-validations documentation page: http://docs.openstack.org/developer/tripleo-validations/readme.html#existing-validations