Merge "Add Troubleshooting chapter and organize the docs there"

doc/source/deploy-overcloud.rst

@@ -14,33 +14,18 @@ Register nodes for your deployment with Ironic::
     instack-ironic-deployment --nodes-json instackenv.json --register-nodes
 
 .. note::
-    It's not recommended to delete nodes and/or rerun this command after
-    you've proceeded to the next steps. Particularly, if you start discovery
-    and then re-register nodes, you won't be able to retry discovery until
-    the previous one times out (1 hour by default).
+   It's not recommended to delete nodes and/or rerun this command after
+   you have proceeded to the next steps. Particularly, if you start discovery
+   and then re-register nodes, you won't be able to retry discovery until
+   the previous one times out (1 hour by default). If you are having issues
+   with nodes after registration, please follow
+   :ref:`node_registration_problems`.
 
-    Any problems with node data registered into Ironic on this step can be
-    fixed using the Ironic CLI.  For example, a wrong MAC can be fixed in two
-    steps:
+Introspecting Nodes
+-------------------
 
-    * Find out the assigned port UUID by running
-      ::
-
-        ironic node-port-list <NODE UUID>
-
-    * Update the MAC address by running
-      ::
-
-        ironic port-update <PORT UUID> replace address=<NEW MAC>
-
-    * A Wrong IPMI address can be fixed with the following command::
-
-        ironic node-update <NODE UUID> replace driver_info/ipmi_address=<NEW IPMI ADDRESS>
-
-Discovering Nodes
------------------
-
-Discover hardware attributes of nodes and match them to a deployment profile:
+Introspect hardware for attributes of nodes and match them to a deployment
+profile:
 
 .. admonition:: Ceph
    :class: ceph-tag
@@ -63,10 +48,9 @@ Check what profiles were matched for the discovered nodes::
 
     instack-ironic-deployment --show-profile
 
-If you have problems with discovery step, please check `ironic-discoverd
-troubleshooting documentation`_.
-
-.. _ironic-discoverd troubleshooting documentation: https://github.com/stackforge/ironic-discoverd#troubleshooting
+.. note:: **Introspection has to finish without errors.**
+   The process can take up to 5 minutes for VM / 15 minutes for baremetal. If
+   the process takes longer, see :ref:`introspection_problems`.
 
 Ready-state configuration
 -------------------------
@@ -106,6 +90,7 @@ Deploy the overcloud (default of 1 compute and 1 control):
    behavior may be changed by setting the environment variable::
 
        export CINDER_ISCSI=1
+
 ::
 
     instack-deploy-overcloud --tuskar

doc/source/environments/virtual.rst

@@ -95,7 +95,8 @@ Preparing the Virtual Environment (Automated)
 
    ::
 
-    curl https://raw.githubusercontent.com/rdo-management/instack-undercloud/master/scripts/instack-setup-host | bash -x
+       curl https://raw.githubusercontent.com/rdo-management/instack-undercloud/master/scripts/instack-setup-host | bash -x
+
 
 #. Install instack-undercloud::
 
@@ -105,7 +106,8 @@ Preparing the Virtual Environment (Automated)
    the same base OS as the host. See the Note below to choose a different
    OS.:
 
-  .. note:: To setup the undercloud vm with a base OS different from the host,
+  .. note::
+     To setup the undercloud vm with a base OS different from the host,
      set the ``$NODE_DIST`` environment variable prior to running
      ``instack-virt-setup``:
 
@@ -171,7 +173,8 @@ Preparing the Virtual Environment (Automated)
 
       instack-virt-setup
 
-   If the script encounters problems, see :doc:`../troubleshooting-virt-setup`.
+   If the script encounters problems, see
+   :doc:`../troubleshooting/troubleshooting-virt-setup`.
 
 When the script has completed successfully it will output the IP address of the
 instack vm that has now been installed with a base OS.

doc/source/index.rst

@@ -17,18 +17,9 @@ Contents:
    Building Images <build-images>
    Deploying the Overcloud <deploy-overcloud>
    Vendor-Specific Setup <vendor-specific>
-   How to Contribute <contributions/contributions>
-
-
-Appendices
-==========
-
-.. toctree::
-
-   Frequently Asked Questions (FAQ) <faq>
    AHC (Automated Health Check) Workflow <ahc-workflow>
-   Troubleshooting instack-virt-setup Failures <troubleshooting-virt-setup>
-   Troubleshooting a Failed Overcloud Deployment <troubleshooting-overcloud>
+   Troubleshooting <troubleshooting/troubleshooting>
+   How to Contribute <contributions/contributions>
 
 
 Documentation Conventions

doc/source/troubleshooting/troubleshooting-nodes.rst

@@ -1,8 +1,8 @@
-Frequently Asked Questions
-==========================
+Troubleshooting Node Management Failures
+========================================
 
-Where are the logs?
-~~~~~~~~~~~~~~~~~~~
+Where Are the Logs?
+-------------------
 
 Some logs are stored in *journald*, but most are stored as text files in
 ``/var/log``.  Ironic and ironic-discoverd logs are stored in journald. Note
@@ -13,8 +13,36 @@ for example to get all ironic-discoverd logs use::
 
     sudo journalctl -u openstack-ironic-discoverd -u openstack-ironic-discoverd-dnsmasq
 
-Discovery FAQ
-~~~~~~~~~~~~~
+
+.. _node_registration_problems:
+
+Node Registration Problems
+--------------------------
+
+Any problems with node data registered into Ironic can be fixed using the
+Ironic CLI.
+
+For example, a wrong MAC can be fixed in two steps:
+
+* Find out the assigned port UUID by running
+  ::
+
+    ironic node-port-list <NODE UUID>
+
+* Update the MAC address by running
+  ::
+
+    ironic port-update <PORT UUID> replace address=<NEW MAC>
+
+A Wrong IPMI address can be fixed with the following command::
+
+    ironic node-update <NODE UUID> replace driver_info/ipmi_address=<NEW IPMI ADDRESS>
+
+
+.. _introspection_problems:
+
+Hardware Introspection Problems
+--------------------------------
 
 Discovery hangs and times out
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -32,12 +60,9 @@ Refusing to introspect node with provision state "available"
 If you're running discovery directly using ironic-discoverd CLI (or in case of
 bugs in our scripts), a node can be in the "AVAILABLE" state, which is meant for
 deployment, not for discovery. You should advance node to the "MANAGEABLE" state
-before discovery and move it back before deployment. While our scripts
-generally do it, they suffer from `bug 1212134
-<https://bugzilla.redhat.com/show_bug.cgi?id=1212134>`_ which may cause nodes
-to be in the wrong state. Please refer to `upstream node states documentation
-<https://github.com/stackforge/ironic-discoverd#node-states>`_ for information
-on how to fix it.
+before discovery and move it back before deployment. Please refer to `upstream
+node states documentation <https://github.com/stackforge/ironic-discoverd
+#node-states>`_ for information on how to fix it.
 
 How can discovery be stopped?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/source/troubleshooting/troubleshooting.rst

@@ -0,0 +1,12 @@
+Troubleshooting
+===============
+
+At this chapter you will find answers for frequently asked questions and
+help with troubleshooting when using RDO-Manager.
+
+
+.. toctree::
+
+   Virtual Setup Problems <troubleshooting-virt-setup>
+   Node Management Problems <troubleshooting-nodes>
+   Failed Overcloud Deployment <troubleshooting-overcloud>