From ea3f54f09a3c1e24fe61a0e90b2ccbf1cdfa8c2d Mon Sep 17 00:00:00 2001 From: Jaromir Coufal Date: Thu, 23 Apr 2015 13:01:25 +0200 Subject: [PATCH] Add Troubleshooting chapter and organize the docs there Change-Id: I37b8314dcaf81da9069d22266c7ebd90a84f5bbb --- doc/source/deploy-overcloud.rst | 43 ++++++---------- doc/source/environments/virtual.rst | 9 ++-- doc/source/index.rst | 13 +---- .../troubleshooting-nodes.rst} | 49 ++++++++++++++----- .../troubleshooting-overcloud.rst | 0 .../troubleshooting-virt-setup.rst | 0 .../troubleshooting/troubleshooting.rst | 12 +++++ 7 files changed, 71 insertions(+), 55 deletions(-) rename doc/source/{faq.rst => troubleshooting/troubleshooting-nodes.rst} (67%) rename doc/source/{ => troubleshooting}/troubleshooting-overcloud.rst (100%) rename doc/source/{ => troubleshooting}/troubleshooting-virt-setup.rst (100%) create mode 100644 doc/source/troubleshooting/troubleshooting.rst diff --git a/doc/source/deploy-overcloud.rst b/doc/source/deploy-overcloud.rst index d216a8c98..43e1be994 100644 --- a/doc/source/deploy-overcloud.rst +++ b/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 - - * Update the MAC address by running - :: - - ironic port-update replace address= - - * A Wrong IPMI address can be fixed with the following command:: - - ironic node-update replace driver_info/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 diff --git a/doc/source/environments/virtual.rst b/doc/source/environments/virtual.rst index f4ca10661..42ba62c45 100644 --- a/doc/source/environments/virtual.rst +++ b/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. diff --git a/doc/source/index.rst b/doc/source/index.rst index a76b6b8a4..580afab19 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,18 +17,9 @@ Contents: Building Images Deploying the Overcloud Vendor-Specific Setup - How to Contribute - - -Appendices -========== - -.. toctree:: - - Frequently Asked Questions (FAQ) AHC (Automated Health Check) Workflow - Troubleshooting instack-virt-setup Failures - Troubleshooting a Failed Overcloud Deployment + Troubleshooting + How to Contribute Documentation Conventions diff --git a/doc/source/faq.rst b/doc/source/troubleshooting/troubleshooting-nodes.rst similarity index 67% rename from doc/source/faq.rst rename to doc/source/troubleshooting/troubleshooting-nodes.rst index d37114235..a02f568e5 100644 --- a/doc/source/faq.rst +++ b/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 + +* Update the MAC address by running + :: + + ironic port-update replace address= + +A Wrong IPMI address can be fixed with the following command:: + + ironic node-update replace driver_info/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 -`_ which may cause nodes -to be in the wrong state. Please refer to `upstream node states documentation -`_ for information -on how to fix it. +before discovery and move it back before deployment. Please refer to `upstream +node states documentation `_ for information on how to fix it. How can discovery be stopped? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/troubleshooting-overcloud.rst b/doc/source/troubleshooting/troubleshooting-overcloud.rst similarity index 100% rename from doc/source/troubleshooting-overcloud.rst rename to doc/source/troubleshooting/troubleshooting-overcloud.rst diff --git a/doc/source/troubleshooting-virt-setup.rst b/doc/source/troubleshooting/troubleshooting-virt-setup.rst similarity index 100% rename from doc/source/troubleshooting-virt-setup.rst rename to doc/source/troubleshooting/troubleshooting-virt-setup.rst diff --git a/doc/source/troubleshooting/troubleshooting.rst b/doc/source/troubleshooting/troubleshooting.rst new file mode 100644 index 000000000..cfc8caa1d --- /dev/null +++ b/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 + Node Management Problems + Failed Overcloud Deployment