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

Change-Id: I304a460f88f3f8ee33cf642355f0e659184db724
Story: #2006963
Task: #40727

doc/source/admin/hardware_managers.rst

@@ -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>`.

doc/source/admin/how_it_works.rst

@@ -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

doc/source/admin/index.rst

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

doc/source/conf.py

@@ -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

doc/source/contributor/hardware_managers.rst

@@ -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