diff --git a/doc/source/advanced_deployment/advanced_deployment.rst b/doc/source/advanced_deployment/advanced_deployment.rst index 24e649ae..c3b10b5d 100644 --- a/doc/source/advanced_deployment/advanced_deployment.rst +++ b/doc/source/advanced_deployment/advanced_deployment.rst @@ -6,6 +6,7 @@ In this chapter you will find advanced deployment of various |project| areas. .. toctree:: + node_states root_device build_single_image introspect_single_node diff --git a/doc/source/advanced_deployment/introspect_single_node.rst b/doc/source/advanced_deployment/introspect_single_node.rst index 045a4cc5..071ce889 100644 --- a/doc/source/advanced_deployment/introspect_single_node.rst +++ b/doc/source/advanced_deployment/introspect_single_node.rst @@ -5,7 +5,8 @@ In addition to bulk introspection, you can also introspect nodes one by one. When doing so, you must take care to set the correct node states manually. Use ``ironic node-show UUID`` command to figure out whether nodes are in ``manageable`` or ``available`` state. For all nodes in ``available`` state, -start with putting a node to ``manageable`` state:: +start with putting a node to ``manageable`` state (see +:doc:`../advanced_deployment/node_states` for details):: ironic node-set-provision-state UUID manage diff --git a/doc/source/advanced_deployment/node_states.rst b/doc/source/advanced_deployment/node_states.rst new file mode 100644 index 00000000..78a602aa --- /dev/null +++ b/doc/source/advanced_deployment/node_states.rst @@ -0,0 +1,58 @@ +Bare Metal Node States +====================== + +This document provides a brief explanation of the bare metal node states that +TripleO uses or might use. Please refer to `the Ironic documentation +`_ for more details. + +enroll +------ + +With recent versions of the bare metal API (starting with 1.11), nodes begin +their life in a state called ``enroll``. Nodes in this state are not available +for deployment, nor for most of other actions. Ironic does not touch such nodes +in any way. + +Starting with the Newton release, TripleO node registration command allows +to import nodes in this state instead of the default ``available``. +To do so pass the option ``--initial-state=enroll``:: + + openstack baremetal import --initial-state=enroll instackenv.json + +Then move the nodes to manageable_ state and eventually to available_. + +manageable +---------- + +To make nodes alive an operator uses ``manage`` provisioning action to move +nodes to ``manageable`` state. During this transition the power and management +credentials (IPMI, SSH, etc) are validated to ensure that nodes in +``manageable`` state are actually manageable by Ironic. This state is still not +available for deployment. With nodes in this state an operator can execute +various pre-deployment actions, such as introspection, RAID configuration, etc. +So to sum it up, nodes in ``manageable`` state are being configured before +exposing them into the cloud. + +Nodes get into ``manageable`` state automatically. The ``manage`` action +can be used to bring nodes already moved to available_ state back to +``manageable`` for configuration:: + + ironic node-set-provision-state manage + + +available +--------- + +The last step before the deployment is to make nodes ``available`` using the +``provide`` provisioning action. Such nodes are exposed to nova, and can be +deployed to at any moment. No long-running configuration actions should be run +in this state. + +.. note:: + The TripleO introspection command ``openstack baremetal introspection bulk + start`` moves ``available`` nodes to manageable_ state automatically + before and moves them back after a successful introspection. However, nodes + which failed introspection stay in ``manageable`` state and must be + reintrospected or made ``available`` manually:: + + ironic node-set-provision-state provide diff --git a/doc/source/advanced_deployment/root_device.rst b/doc/source/advanced_deployment/root_device.rst index 24fbdfbf..7c6eb026 100644 --- a/doc/source/advanced_deployment/root_device.rst +++ b/doc/source/advanced_deployment/root_device.rst @@ -27,6 +27,32 @@ Where the new value is calculated as a real disk size in GiB minus 1 GiB to account for partitioning (the introspection process does this calculation automatically). +Setting root device hints automatically +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting with the Newton release it is possible to autogenerate root device +hints for all nodes instead of setting them one by one. Pass the +``--root-device`` argument to the ``openstack baremetal configure boot`` +**after a successful introspection**. This argument can accept a device list +in the order of preference, for example:: + + openstack baremetal configure boot --root-device=sdb,sdc,vda + +It can also accept one of two strategies: ``smallest`` will pick the smallest +device, ``largest`` will pick the largest one. By default only disk devices +larger than 4 GiB are considered at all, set the ``--root-device-minimum-size`` +argument to change. + +.. note:: + Subsequent runs of this command on the same set of nodes does nothing, + as root device hints are already recorded on nodes and are not overwritten. + If you want to change existing root device hints, first remove them manually + as described above. + +.. note:: + This command relies on introspection data, so if you change disk devices on + the machines, introspection must be rerun before rerunning this command. + Using introspection data to find the root device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/basic_deployment/basic_deployment_cli.rst b/doc/source/basic_deployment/basic_deployment_cli.rst index 7d95b204..222a7f1c 100644 --- a/doc/source/basic_deployment/basic_deployment_cli.rst +++ b/doc/source/basic_deployment/basic_deployment_cli.rst @@ -175,24 +175,42 @@ Load the images into the undercloud Glance:: Register Nodes -------------- -Register nodes for your deployment with Ironic:: +Register and configure nodes for your deployment with Ironic:: openstack baremetal import instackenv.json -.. note:: - The file to be imported may be either JSON, YAML or CSV format, and - the type is detected via the file extension (json, yaml, csv). +The file to be imported may be either JSON, YAML or CSV format, and +the type is detected via the file extension (json, yaml, csv). +The file format is documented in :ref:`instackenv`. .. admonition:: Stable Branch :class: stable - If you're running an old (stable/liberty or older) tripleoclient version - however then you must specify --json explicitly and only use that format. + For TripleO release Liberty and older an explicit ``--json`` or ``--csv`` + flag is required for JSON and CSV formats accordingly. -.. note:: - The file format for node import is documented, see :ref:`instackenv`. +.. admonition:: Stable Branch + :class: stable -.. note:: + For TripleO release Mitaka and older the following command must be run + after registration to assign the deployment kernel and ramdisk to all nodes: + + openstack baremetal configure boot + +Starting with the Newton release you can take advantage of the ``enroll`` +provisioning state - see :doc:`../advanced_deployment/node_states` for details. + +If your hardware has several hard drives, it's highly recommended that you +specify the exact device to be used during introspection and deployment +as a root device. Please see :ref:`root_device` for details. + +.. warning:: + If you don't specify the root device explicitly, any device may be picked. + Also the device chosen automatically is **NOT** guaranteed to be the same + across rebuilds. Make sure to wipe the previous installation before + rebuilding in this case. + +.. warning:: It's not recommended to delete nodes and/or rerun this command after you have proceeded to the next steps. Particularly, if you start introspection and then re-register nodes, you won't be able to retry introspection until @@ -200,41 +218,6 @@ Register nodes for your deployment with Ironic:: with nodes after registration, please follow :ref:`node_registration_problems`. -.. note:: - By default Ironic will not sync the power state of the nodes, - because in our HA (high availability) model Pacemaker is the - one responsible for controlling the power state of the nodes - when fencing. If you are using a non-HA setup and want Ironic - to take care of the power state of the nodes please change the - value of the "force_power_state_during_sync" configuration option - in the /etc/ironic/ironic.conf file to "True" and restart the - openstack-ironic-conductor service. - - Also, note that if ``openstack undercloud install`` is re-run the value of - the "force_power_state_during_sync" configuration option will be set back to - the default, which is "False". - -.. note:: - If you want to take advantage of the ENROLL provisioning state introduced in - OpenStack Liberty, you must enable an Ironic API version >= 1.11 (for - instance by setting the OS_BAREMETAL_API_VERSION environment variable), and - pass the option ``--initial-state=enroll`` to ``openstack baremetal - import``. - -Assign kernel and ramdisk to nodes:: - - openstack baremetal configure boot - -.. note:: - If your hardware has several hard drives, it's highly recommended that you - specify the exact device to be used during introspection and deployment - as a root device. Please see :ref:`root_device` for details. - - If you don't specify the root device explicitly, any device may be picked. - Also the device chosen automatically is NOT guaranteed to be the same - across rebuilds. Make sure to wipe the previous installation before - rebuilding in this case. - .. _introspection: Introspect Nodes diff --git a/doc/source/troubleshooting/troubleshooting-nodes.rst b/doc/source/troubleshooting/troubleshooting-nodes.rst index a8623999..ff02928e 100644 --- a/doc/source/troubleshooting/troubleshooting-nodes.rst +++ b/doc/source/troubleshooting/troubleshooting-nodes.rst @@ -42,6 +42,22 @@ A Wrong IPMI address can be fixed with the following command:: ironic node-update replace driver_info/ipmi_address= +Node power state is not enforced by Ironic +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default Ironic will not forcibly sync the power state of the nodes, +because in our HA (high availability) model Pacemaker is the +one responsible for controlling the power state of the nodes +when fencing. If you are using a non-HA setup and want Ironic +to take care of the power state of the nodes please change the +value of the ``force_power_state_during_sync`` configuration option +in the ``/etc/ironic/ironic.conf`` file to ``True`` and restart the +openstack-ironic-conductor service. + +Also, note that if ``openstack undercloud install`` is re-run the value of +the ``force_power_state_during_sync`` configuration option will be set back to +the default, which is ``False``. + .. _introspection_problems: