Document in-band deploy steps and add more docs for custom steps

Change-Id: I304a460f88f3f8ee33cf642355f0e659184db724
Story: #2006963
Task: #40727
This commit is contained in:
Dmitry Tantsur 2020-08-24 17:39:54 +02:00
parent 3faf13bbb4
commit ffacb713e5
5 changed files with 154 additions and 17 deletions

View File

@ -0,0 +1,45 @@
==========================
Built-in hardware managers
==========================
GenericHardwareManager
======================
This is the default hardware manager for ironic-python-agent. It provides
support for :ref:`hardware-inventory` and the default deploy and clean steps.
Deploy steps
------------
``deploy.write_image(node, ports, image_info, configdrive=None)``
A deploy step backing the ``write_image`` deploy step of the
:ironic-doc:`direct deploy interface
<admin/interfaces/deploy.html#direct-deploy>`.
Should not be used explicitly, but can be overridden to provide a custom
way of writing an image.
``deploy.erase_device_metadata(node, ports)``
Erases partition tables from all recognized disk devices. Can be used with
software RAID since it requires empty holder disks.
``raid.apply_configuration(node, ports, raid_config, delete_existing=True)``
Apply a software RAID configuration. It belongs to the ``raid`` interface
and must be used through the :ironic-doc:`ironic RAID feature
<admin/raid.html>`.
Clean steps
-----------
``deploy.erase_devices``
Securely erases all information from all recognized disk devices.
Relatively fast when secure ATA erase is available, otherwise can take
hours, especially on a virtual environment. Enabled by default.
``deploy.erase_device_metadata``
Erases partition tables from all recognized disk devices. Can be used as
an alternative to the much longer ``erase_devices`` step.
``raid.create_configuration``
Create a RAID configuration. This step belongs to the ``raid`` interface
and must be used through the :ironic-doc:`ironic RAID feature
<admin/raid.html>`.
``raid.delete_configuration``
Delete the RAID configuration. This step belongs to the ``raid`` interface
and must be used through the :ironic-doc:`ironic RAID feature
<admin/raid.html>`.

View File

@ -148,6 +148,8 @@ collectors are:
.. _hardware: https://pypi.org/project/hardware/
.. _NUMA: https://en.wikipedia.org/wiki/Non-uniform_memory_access
.. _hardware-inventory:
Hardware Inventory
------------------
IPA collects various hardware information using its

View File

@ -4,5 +4,6 @@ Ironic Python Agent Administration
.. toctree::
how_it_works
hardware_managers
rescue
troubleshooting

View File

@ -11,6 +11,7 @@ extensions = ['sphinx.ext.autodoc',
openstackdocs_projects = [
'ironic',
'ironic-inspector',
'ironic-lib',
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy

View File

@ -7,8 +7,8 @@ Hardware managers are how IPA supports multiple different hardware platforms
in the same agent. Any action performed on hardware can be overridden by
deploying your own hardware manager.
IPA ships with GenericHardwareManager, which implements basic cleaning and
deployment methods compatible with most hardware.
IPA ships with :doc:`GenericHardwareManager </admin/hardware_managers>`, which
implements basic cleaning and deployment methods compatible with most hardware.
How are methods executed on HardwareManagers?
---------------------------------------------
@ -38,10 +38,13 @@ evaluate_hardware_support(), which should return one of the enums
in hardware.HardwareSupport. Hardware support determines which hardware
manager is executed first for a given function (see: "`How are methods
executed on HardwareManagers?`_" for more info). Common methods you
may want to implement are list_hardware_info(), to add additional hardware
the GenericHardwareManager is unable to identify and erase_devices(), to
may want to implement are ``list_hardware_info()``, to add additional hardware
the GenericHardwareManager is unable to identify and ``erase_devices()``, to
erase devices in ways other than ATA secure erase or shredding.
Some reusable functions are provided by :ironic-lib-doc:`ironic-lib
<reference/api/modules.html>`, its IPA is relatively stable.
The examples_ directory has two example hardware managers that can be copied
and adapter for your use case.
@ -59,19 +62,24 @@ and then return the combined list to Ironic.
To expose extra clean steps, the custom hardware manager should have a function
named `get_clean_steps()` which returns a list of dictionaries. The
dictionaries should be in the form::
dictionaries should be in the form:
.. code-block:: python
def get_clean_steps(self, node, ports):
return [
{
// A function on the custom hardware manager
# A function on the custom hardware manager
'step': 'upgrade_firmware',
// An integer priority. Largest priorities are executed first
# An integer priority. Largest priorities are executed first
'priority': 10,
// Should always be the deploy interface
# Should always be the deploy interface
'interface': 'deploy',
// Request the node to be rebooted out of band by Ironic when the
// step completes successfully
# Request the node to be rebooted out of band by Ironic when
# the step completes successfully
'reboot_requested': False
}
]
Then, you should create functions which match each of the `step` keys in
the clean steps you return. The functions will take two parameters: `node`,
@ -87,7 +95,9 @@ further managers are called. If the function raises
`IncompatibleHardwareMethodError`, the next manager will be called. If the
function raises any other exception, the command will be considered failed,
the command result's error message will be set to the exception's error
message, and no further managers will be called. An example step::
message, and no further managers will be called. An example step:
.. code-block:: python
def upgrade_firmware(self, node, ports):
if self._device_exists():
@ -102,6 +112,84 @@ message, and no further managers will be called. An example step::
be set to whichever manager has a higher hardware support level and then
use the higher priority in the case of a tie.
Custom HardwareManagers and Deploying
-------------------------------------
Starting with the Victoria release cycle, :ironic-doc:`deployment
<admin/node-deployment.html>` can be customized similarly to `cleaning
<Custom HardwareManagers and Cleaning>`_. A hardware manager can define *deploy
steps* that may be run during deployment by exposing a ``get_deploy_steps``
call.
There are two kinds of deploy steps:
#. Steps that need to be run automatically must have a non-zero priority and
cannot take required arguments. For example:
.. code-block:: python
def get_deploy_steps(self, node, ports):
return [
{
# A function on the custom hardware manager
'step': 'upgrade_firmware',
# An integer priority. Largest priorities are executed first
'priority': 10,
# Should always be the deploy interface
'interface': 'deploy',
}
]
# A deploy steps looks the same as a clean step.
def upgrade_firmware(self, node, ports):
if self._device_exists():
# Do the upgrade
return 'upgraded firmware'
else:
raise errors.IncompatibleHardwareMethodError()
Priority should be picked based on when exactly in the process the step will
run. See :ironic-doc:`agent step priorities
<admin/node-deployment.html#agent-steps>` for guidance.
#. Steps that will be requested via :ironic-doc:`deploy templates
<admin/node-deployment.html#deploy-templates>` should have a priority of 0
and may take both required and optional arguments that will be provided via
the deploy templates. For example:
.. code-block:: python
def get_deploy_steps(self, node, ports):
return [
{
# A function on the custom hardware manager
'step': 'write_a_file',
# Steps with priority 0 don't run by default.
'priority': 0,
# Should be the deploy interface, unless there is driver-side
# support for another interface (as it is for RAID).
'interface': 'deploy',
# Arguments that can be required or optional.
'argsinfo': {
'path': {
'description': 'Path to file',
'required': True,
},
'content': {
'description': 'Content of the file',
'required': True,
},
'mode': {
'description': 'Mode of the file, defaults to 0644',
'required': False,
},
}
}
]
def write_a_file(self, node, ports, path, contents, mode=0o644):
pass # Mount the disk, write a file.
Versioning
~~~~~~~~~~
Each hardware manager has a name and a version. This version is used during