diff --git a/doc/source/admin/deploy-steps.rst b/doc/source/admin/deploy-steps.rst index 1e4b68c8ff..1c02da9a73 100644 --- a/doc/source/admin/deploy-steps.rst +++ b/doc/source/admin/deploy-steps.rst @@ -1,65 +1,5 @@ ============ -Deploy steps +Deploy Steps ============ -Overview -======== - -Node deployment is performed by the Bare Metal service to prepare a node for -use by a workload. The exact work flow used depends on a number of factors, -including the hardware type and interfaces assigned to a node. - -Customizing deployment -====================== - -The Bare Metal service implements deployment by collecting a list of deploy -steps to perform on a node from the Power, Deploy, Management, BIOS, and RAID -interfaces of the driver assigned to the node. These steps are then ordered by -priority and executed on the node when the node is moved to the ``deploying`` -state. - -Nodes move to the ``deploying`` state when attempting to move to the ``active`` -state (when the hardware is prepared for use by a workload). For a full -understanding of all state transitions into deployment, please see -:ref:`states`. - -The Bare Metal service added support for deploy steps in the Rocky release. - -Deploy steps ------------- - -Deploy steps are ordered from higher to lower priority, where a larger integer -is a higher priority. If the same priority is used by deploy steps on different -interfaces, the following resolution order is used: Power, Management, Deploy, -BIOS, and RAID interfaces. - -Writing a Deploy Step ---------------------- - -Please refer to :doc:`/contributor/deploy-steps`. - -FAQ -=== - -What deploy step is running? ----------------------------- -To check what deploy step the node is performing or attempted to perform and -failed, run the following command; it will return the value in the node's -``driver_internal_info`` field:: - - openstack baremetal node show $node_ident -f value -c driver_internal_info - -The ``deploy_steps`` field will contain a list of all remaining steps with -their priorities, and the first one listed is the step currently in progress or -that the node failed before going into ``deploy failed`` state. - -Troubleshooting -=============== -If deployment fails on a node, the node will be put into the ``deploy failed`` -state until the node is deprovisioned. A deprovisioned node is moved to the -``available`` state after the cleaning process has been performed successfully. - -Strategies for determining why a deploy step failed include checking the ironic -conductor logs, checking logs from the ironic-python-agent that have been -stored on the ironic conductor, or performing general hardware troubleshooting -on the node. +The deploy steps section has moved to :ref:`node-deployment-deploy-steps`. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 5edf6ef2c4..6c348620b8 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -11,7 +11,7 @@ the services. Drivers, Hardware Types and Hardware Interfaces Ironic Python Agent Node Hardware Inspection - Deploy steps + Node Deployment Node Cleaning Node Adoption RAID Configuration @@ -32,6 +32,11 @@ the services. Windows Images Troubleshooting FAQ +.. toctree:: + :hidden: + + deploy-steps + Dashboard Integration --------------------- diff --git a/doc/source/admin/node-deployment.rst b/doc/source/admin/node-deployment.rst new file mode 100644 index 0000000000..e4a78b8b0b --- /dev/null +++ b/doc/source/admin/node-deployment.rst @@ -0,0 +1,313 @@ +=============== +Node Deployment +=============== + +Overview +======== + +Node deployment is performed by the Bare Metal service to prepare a node for +use by a workload. The exact work flow used depends on a number of factors, +including the hardware type and interfaces assigned to a node. + +.. contents:: + :depth: 2 + +.. _node-deployment-deploy-steps: + +Deploy Steps +============ + +The Bare Metal service implements deployment by collecting a list of deploy +steps to perform on a node from the Power, Deploy, Management, BIOS, and RAID +interfaces of the driver assigned to the node. These steps are then ordered by +priority and executed on the node when the node is moved to the ``deploying`` +state. + +Nodes move to the ``deploying`` state when attempting to move to the ``active`` +state (when the hardware is prepared for use by a workload). For a full +understanding of all state transitions into deployment, please see +:doc:`../contributor/states`. + +The Bare Metal service added support for deploy steps in the Rocky release. + +Order of execution +------------------ + +Deploy steps are ordered from higher to lower priority, where a larger integer +is a higher priority. If the same priority is used by deploy steps on different +interfaces, the following resolution order is used: Power, Management, Deploy, +BIOS, and RAID interfaces. + +.. _node-deployment-core-steps: + +Core steps +---------- + +Certain default deploy steps are designated as 'core' deploy steps. The +following deploy steps are core: + +``deploy.deploy`` + In this step the node is booted using a provisioning image, and the user + image is written to the node's disk. It has a priority of 100. + +Writing a Deploy Step +--------------------- + +Please refer to :doc:`/contributor/deploy-steps`. + +FAQ +--- + +What deploy step is running? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To check what deploy step the node is performing or attempted to perform and +failed, run the following command; it will return the value in the node's +``driver_internal_info`` field:: + + openstack baremetal node show $node_ident -f value -c driver_internal_info + +The ``deploy_steps`` field will contain a list of all remaining steps with +their priorities, and the first one listed is the step currently in progress or +that the node failed before going into ``deploy failed`` state. + +Troubleshooting +--------------- +If deployment fails on a node, the node will be put into the ``deploy failed`` +state until the node is deprovisioned. A deprovisioned node is moved to the +``available`` state after the cleaning process has been performed successfully. + +Strategies for determining why a deploy step failed include checking the ironic +conductor logs, checking logs from the ironic-python-agent that have been +stored on the ironic conductor, or performing general hardware troubleshooting +on the node. + +Deploy Templates +================ + +Starting with the Stein release, with Bare Metal API version 1.55, deploy +templates offer a way to define a set of one or more deploy steps to be +executed with particular sets of arguments and priorities. + +Each deploy template has a name, which must be a valid trait. Traits can be +either standard or custom. Standard traits are listed in the `os_traits +library `_. Custom traits must +meet the following requirements: + +* prefixed with ``CUSTOM_`` +* contain only upper case characters A to Z, digits 0 to 9, or underscores +* no longer than 255 characters in length + +Deploy step format +------------------ + +An invocation of a deploy step is defined in a deploy template as follows:: + + { + "interface": "", + "step": "", + "args": { + "": "", + "": "" + }, + "priority": + } + +A deploy template contains a list of one or more such steps. Each combination +of `interface` and `step` may only be specified once in a deploy template. + +Matching deploy templates +------------------------- + +During deployment, if any of the traits in a node's ``instance_info.traits`` +field match the name of a deploy template, then the steps from that deploy +template will be added to the list of steps to be executed by the node. + +When using the Compute service, any traits in the instance's flavor properties +or image properties are stored in ``instance_info.traits`` during deployment. +See :ref:`scheduling-traits` for further information on how traits are used for +scheduling when the Bare Metal service is used with the Compute service. + +Note that there is no ongoing relationship between a node and any templates +that are matched during deployment. The set of matching deploy templates is +checked at deployment time. Any subsequent updates to or deletion of those +templates will not be reflected in the node's configuration unless it is +redeployed or rebuilt. Similarly, if a node is rebuilt and the set of matching +deploy templates has changed since the initial deployment, then the resulting +configuration of the node may be different from the initial deployment. + +Overriding default deploy steps +------------------------------- + +A deploy step is enabled by default if it has a non-zero default priority. +A default deploy step may be overridden in a deploy template. If the step's +priority is a positive integer it will be executed with the specified priority +and arguments. If the step's priority is zero, the step will not be executed. + +If a `core deploy step `_ is included in a +deploy template, it can only be assigned a priority of zero to disable it. + +Creating a deploy template via API +---------------------------------- + +A deploy template can be created using the Bare Metal API:: + + POST /v1/deploy_templates + +Here is an example of the body of a request to create a deploy template with a +single step: + +.. code-block:: json + + { + "name": "CUSTOM_HYPERTHREADING_ON", + "steps": [ + { + "interface": "bios", + "step": "apply_configuration", + "args": { + "settings": [ + { + "name": "LogicalProc", + "value": "Enabled" + } + ] + }, + "priority": 150 + } + ] + } + +Further information on this API is available `here +`__. + +Creating a deploy template via "openstack baremetal" client +----------------------------------------------------------- + +A deploy template can be created via the ``openstack baremetal deploy template +create`` command, starting with ``python-ironicclient`` 2.7.0. + +The argument ``--steps`` must be specified. Its value is one of: + +- a JSON string +- path to a JSON file whose contents are passed to the API +- '-', to read from stdin. This allows piping in the deploy steps. + +Example of creating a deploy template with a single step using a JSON string: + +.. code-block:: console + + openstack baremetal deploy template create \ + CUSTOM_HYPERTHREADING_ON \ + --steps '[{"interface": "bios", "step": "apply_configuration", "args": {"settings": [{"name": "LogicalProc", "value": "Enabled"}]}, "priority": 150}]' + +Or with a file: + +.. code-block:: console + + openstack baremetal deploy template create \ + CUSTOM_HYPERTHREADING_ON \ + ---steps my-deploy-steps.txt + +Or with stdin: + +.. code-block:: console + + cat my-deploy-steps.txt | openstack baremetal deploy template create \ + CUSTOM_HYPERTHREADING_ON \ + --steps - + +Example of use with the Compute service +--------------------------------------- + +.. note:: The deploy steps used in this example are for example purposes only. + +In the following example, we have a node with the following node traits: + +.. code-block:: json + + [ + "CUSTOM_HYPERTHREADING_ON" + ] + +We also have a flavor, ``bm-hyperthreading-on``, in the Compute service with +the following property:: + + trait:CUSTOM_HYPERTHREADING_ON:required + +Creating a Compute instance with this flavor will ensure that the instance is +scheduled only to Bare Metal nodes with the ``CUSTOM_HYPERTHREADING_ON`` trait. + +We could then create a Bare Metal deploy template with the name +``CUSTOM_HYPERTHREADING_ON`` and a deploy step that enables Hyperthreading: + +.. code-block:: json + + { + "name": "CUSTOM_HYPERTHREADING_ON", + "steps": [ + { + "interface": "bios", + "step": "apply_configuration", + "args": { + "settings": [ + { + "name": "LogicalProc", + "value": "Enabled" + } + ] + }, + "priority": 150 + } + ] + } + +When an instance is created using the ``bm-hyperthreading-on`` flavor, then the +deploy steps of deploy template ``CUSTOM_HYPERTHREADING_ON`` will be executed +during the deployment of the scheduled node, causing Hyperthreading to be +enabled in the node's BIOS configuration. + +To make this example more dynamic, consider adding a second trait to the node: + +.. code-block:: json + + [ + "CUSTOM_HYPERTHREADING_ON", + "CUSTOM_HYPERTHREADING_OFF" + ] + +We could also create a second flavor, ``bm-hyperthreading-off``, with the +following property:: + + trait:CUSTOM_HYPERTHREADING_OFF:required + +Finally, we create a deploy template with the name +``CUSTOM_HYPERTHREADING_OFF`` and a different set of deploy steps: + +.. code-block:: json + + { + "name": "CUSTOM_HYPERTHREADING_OFF", + "steps": [ + { + "interface": "bios", + "step": "apply_configuration", + "args": { + "settings": [ + { + "name": "LogicalProc", + "value": "Disabled" + } + ] + }, + "priority": 150 + } + ] + } + +Creating a Compute instance with the ``bm-hyperthreading-off`` instance will +cause the scheduled node to have Hyperthreading disabled in the BIOS during +deployment. + +We now have a way to create Compute instances with different configurations, by +choosing between different Compute flavors, supported by a single Bare Metal +node that is dynamically configured during deployment. diff --git a/doc/source/admin/notifications.rst b/doc/source/admin/notifications.rst index f9b5397906..b84133d266 100644 --- a/doc/source/admin/notifications.rst +++ b/doc/source/admin/notifications.rst @@ -118,6 +118,53 @@ Example of chassis CRUD notification:: "publisher_id":"ironic-api.hostname02" } +List of CRUD notifications for deploy template: + +* ``baremetal.deploy_template.create.start`` +* ``baremetal.deploy_template.create.end`` +* ``baremetal.deploy_template.create.error`` +* ``baremetal.deploy_template.update.start`` +* ``baremetal.deploy_template.update.end`` +* ``baremetal.deploy_template.update.error`` +* ``baremetal.deploy_template.delete.start`` +* ``baremetal.deploy_template.delete.end`` +* ``baremetal.deploy_template.delete.error`` + +Example of deploy template CRUD notification:: + + { + "priority": "info", + "payload":{ + "ironic_object.namespace":"ironic", + "ironic_object.name":"DeployTemplateCRUDPayload", + "ironic_object.version":"1.0", + "ironic_object.data":{ + "created_at": "2019-02-10T10:13:03+00:00", + "extra": {}, + "name": "CUSTOM_HYPERTHREADING_ON", + "steps": [ + { + "interface": "bios", + "step": "apply_configuration", + "args": { + "settings": [ + { + "name": "LogicalProc", + "value": "Enabled" + } + ] + }, + "priority": 150 + } + ], + "updated_at": "2019-02-27T21:11:03+00:00", + "uuid": "1910f669-ce8b-43c2-b1d8-cf3d65be815e" + } + }, + "event_type":"baremetal.deploy_template.update.end", + "publisher_id":"ironic-api.hostname02" + } + List of CRUD notifications for node: * ``baremetal.node.create.start``