diff --git a/doc/source/basic_deployment/basic_deployment_cli.rst b/doc/source/basic_deployment/basic_deployment_cli.rst index dcffa8d0..db9d0de6 100644 --- a/doc/source/basic_deployment/basic_deployment_cli.rst +++ b/doc/source/basic_deployment/basic_deployment_cli.rst @@ -297,6 +297,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 @@ -345,6 +356,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:: @@ -421,6 +442,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 ^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/environments/baremetal.rst b/doc/source/environments/baremetal.rst index 8ef1ed89..ca0d0a25 100644 --- a/doc/source/environments/baremetal.rst +++ b/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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/index.rst b/doc/source/index.rst index 54324524..10aad48d 100644 --- a/doc/source/index.rst +++ b/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 @@ -97,5 +98,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. diff --git a/doc/source/installation/installing.rst b/doc/source/installation/installing.rst index e796424a..aac01183 100644 --- a/doc/source/installation/installing.rst +++ b/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:: diff --git a/doc/source/introduction/components.rst b/doc/source/introduction/components.rst index 81562679..aac1bc96 100644 --- a/doc/source/introduction/components.rst +++ b/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 ---------- diff --git a/doc/source/validations/validations.rst b/doc/source/validations/validations.rst new file mode 100644 index 00000000..5c2f8b13 --- /dev/null +++ b/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