openstack/bifrost
Code Issues Proposed changes

Merge "Clean up troubleshooting.rst markup"

Browse Source
This commit is contained in:
Jenkins 2015-09-14 03:48:50 +00:00 committed by Gerrit Code Review
commit 197c22308c
3 changed files with 37 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/index.rst
View File

@ -8,6 +8,7 @@ Contents:
readme readme
contributing contributing
troubleshooting
Vagrant Vagrant
deploy/dhcp deploy/dhcp
offline-install offline-install

1
doc/source/troubleshooting.rst Normal file
View File

@ -0,0 +1 @@
.. include:: ../../troubleshooting.rst

68
troubleshooting.rst
View File

@ -1,21 +1,22 @@
=============== ===============
Troubleshooting Troubleshooting
=============== ===============
*********** ***********
Firewalling Firewalling
*********** ***********
Due to the nature of firewall settings and customizations, Bifrost does Due to the nature of firewall settings and customizations, bifrost does
**not** change any local firewalling on the node. Users must ensure that **not** change any local firewalling on the node. Users must ensure that
their firewalling for the node running bifrost is such that the nodes that their firewalling for the node running bifrost is such that the nodes that
are being booted can connect to the following ports:: are being booted can connect to the following ports::
67/UDP for DHCP requests to be serviced 67/UDP for DHCP requests to be serviced
69/UDP for TFTP file transfers (Initial iPXE binary) 69/UDP for TFTP file transfers (Initial iPXE binary)
6301/TCP for the Ironic API 6301/TCP for the ironic API
8080/TCP for HTTP File Downloads (iPXE, Ironic-Python-Agent) 8080/TCP for HTTP File Downloads (iPXE, Ironic-Python-Agent)
If you encounter any additional issues, use of tcpdump is highly recommended If you encounter any additional issues, use of ``tcpdump`` is highly recommended
while attempting to deploy a single node in order to capture and review the while attempting to deploy a single node in order to capture and review the
traffic exchange between the two nodes. traffic exchange between the two nodes.
@ -23,15 +24,15 @@ traffic exchange between the two nodes.
NodeLocked Errors NodeLocked Errors
***************** *****************
This is due to node status checking thread in Ironic, which is a locking This is due to node status checking thread in ironic, which is a locking
action as it utilizes IPMI. The best course of action is to retry the action as it utilizes IPMI. The best course of action is to retry the
operation. If this is occurring with a high frequency, tuning might be operation. If this is occurring with a high frequency, tuning might be
required. required.
Example error: Example error::
| NodeLocked: Node 00000000-0000-0000-0000-046ebb96ec21 is locked by NodeLocked: Node 00000000-0000-0000-0000-046ebb96ec21 is locked by
host $HOSTNAME, please retry after the current operation is completed. host $HOSTNAME, please retry after the current operation is completed.
********************************************* *********************************************
Unexpected/Unknown failure with the IPA Agent Unexpected/Unknown failure with the IPA Agent
@ -47,7 +48,7 @@ file for deployments. The default location for this folder is
Additionally, a playbook has been included that can be used prior to a Additionally, a playbook has been included that can be used prior to a
re-installation to ensure fresh images are deployed. This playbook can re-installation to ensure fresh images are deployed. This playbook can
be found at playbooks/cleanup-deployment-images.yaml be found at ``playbooks/cleanup-deployment-images.yaml``.
Building an IPA image Building an IPA image
===================== =====================
@ -63,15 +64,15 @@ http://git.openstack.org/cgit/openstack/ironic-python-agent/tree/imagebuild/core
This essentially boils down to the following steps: This essentially boils down to the following steps:
1. `git clone https://git.openstack.org/openstack/ironic-python-agent` #. ``git clone https://git.openstack.org/openstack/ironic-python-agent``
2. `cd ironic-python-agent` #. ``cd ironic-python-agent``
3. `pip install -r ./requirements.txt` #. ``pip install -r ./requirements.txt``
4. If you don't already have docker installed, execute: #. If you don't already have docker installed, execute:
`sudo apt-get install docker docker.io` ``sudo apt-get install docker docker.io``
5. `cd imagebuild/coreos` #. ``cd imagebuild/coreos``
6. Edit oem/cloudconfig.yml and add "--debug" to the end of the ExecStart #. Edit ``oem/cloudconfig.yml`` and add ``--debug`` to the end of the ExecStart
setting for the ironic-python-agent.service unit. setting for the ironic-python-agent.service unit.
7. Execute `make` to complete the build process. #. Execute ``make`` to complete the build process.
Once your build is completed, you will need to copy the images files written Once your build is completed, you will need to copy the images files written
to the UPLOAD folder, into the /httpboot folder. If your utilizing the to the UPLOAD folder, into the /httpboot folder. If your utilizing the
@ -84,25 +85,26 @@ deployment process.
Obtaining IPA logs via the console Obtaining IPA logs via the console
================================== ==================================
1) By default, Bifrost sets the agent journal to be logged to the system 1) By default, bifrost sets the agent journal to be logged to the system
console. Due to the variation in hardware, you may need to tune the console. Due to the variation in hardware, you may need to tune the
parameters passed to the deployment ramdisk. This can be done, as shown parameters passed to the deployment ramdisk. This can be done, as shown
below in ironic.conf:: below in ironic.conf::
agent_pxe_append_params=nofb nomodeset vga=normal console=ttyS0 systemd.journald.forward_to_console=yes agent_pxe_append_params=nofb nomodeset vga=normal console=ttyS0 systemd.journald.forward_to_console=yes
Parameters will vary by your hardware type and configuration, however the Parameters will vary by your hardware type and configuration,
systemd.journald.forward_to_console=yes setting is a default, and will only however the ``systemd.journald.forward_to_console=yes`` setting is
work for systemd based IPA images such as the default CoreOS image. a default, and will only work for systemd based IPA images such as
the default CoreOS image.
The example above, effectively disables all attempts by the Kernel to set The example above, effectively disables all attempts by the kernel to set
the video mode, defines the console as ttyS0 or the first serial port, and the video mode, defines the console as ttyS0 or the first serial port, and
instructs systemd to direct logs to the console. instructs systemd to direct logs to the console.
2) Once set, restart the ironic-conductor service, e.g. 2) Once set, restart the ironic-conductor service, e.g.
`service ironic-conductor restart` and attempt to redeploy the node. ``service ironic-conductor restart`` and attempt to redeploy the node.
You will want to view the system console occurring. If possible, you You will want to view the system console occurring. If possible, you
may wish to use ipmitool and write the output to a log file. may wish to use ``ipmitool`` and write the output to a log file.
Gaining access via SSH to the node running IPA Gaining access via SSH to the node running IPA
============================================== ==============================================
@ -110,8 +112,8 @@ Gaining access via SSH to the node running IPA
If you wish to SSH into the node in order to perform any sort of post-mortem, If you wish to SSH into the node in order to perform any sort of post-mortem,
you will need to do the following: you will need to do the following:
1) Set an sshkey="ssh-rsa AAAA....." value on the agent_pxe_append_params 1) Set an ``sshkey="ssh-rsa AAAA....."`` value on the
setting in /etc/ironic/ironic.conf ``agent_pxe_append_params`` setting in ``/etc/ironic/ironic.conf``
2) You will need to short circuit the ironic conductor process. An ideal 2) You will need to short circuit the ironic conductor process. An ideal
place to do so is in ``ironic/drivers/modules/agent.py`` in the place to do so is in ``ironic/drivers/modules/agent.py`` in the
@ -120,11 +122,11 @@ you will need to do the following:
the node, but the node should stay online after IPA has completed the node, but the node should stay online after IPA has completed
deployment. deployment.
3) ssh -l core <ip-address-of-node> 3) ``ssh -l core <ip-address-of-node>``
******************************** ************************************
ssh_public_key_path is not valid ``ssh_public_key_path is not valid``
******************************** ************************************
Bifrost requires that the user who executes bifrost have an SSH key in Bifrost requires that the user who executes bifrost have an SSH key in
their user home, or that the user defines a variable to tell bifrost where their user home, or that the user defines a variable to tell bifrost where
@ -134,15 +136,15 @@ deployment playbook can be re-run.
Generating a new ssh key Generating a new ssh key
======================== ========================
See the manual page for the ssh-keygen command. See the manual page for the ``ssh-keygen`` command.
Defining a specific public key file Defining a specific public key file
=================================== ===================================
A user can define a specific public key file by utilizing the A user can define a specific public key file by utilizing the
ssh_public_key_path variable. This can be set in the ``ssh_public_key_path`` variable. This can be set in the
group_vars/inventory/all file, or on the ansible-playbook command ``group_vars/inventory/all`` file, or on the ``ansible-playbook`` command
line utilizing the -e command line parameter. line utilizing the ``-e`` command line parameter.
Example:: Example::