Redfish driver firmware update

This patch adds support for performing firmware updates using the
redfish and idrac hardware types.

Co-Authored-By: Aija Jaunteva <aija.jaunteva@dell.com>

Change-Id: Ie8f3f68c4a771121ec0ee13ce9349c7cd2b1e567
Depends-On: https://review.opendev.org/#/c/745950
Story: 2008140
Task: 40872

2 files changed, 139 insertions, 2 deletions

diff --git a/doc/source/admin/drivers/idrac.rst b/doc/source/admin/drivers/idrac.rst
index 796b09edb..35acc3ba5 100644
--- a/doc/source/admin/drivers/idrac.rst
+++ b/doc/source/admin/drivers/idrac.rst
@@ -17,7 +17,7 @@ hardware types, though with smaller feature sets.
 Key features of the Dell iDRAC driver include:
 
 * Out-of-band node inspection
-* Boot device management
+* Boot device management and firmware management
 * Power management
 * RAID controller management and RAID volume configuration
 * BIOS settings configuration
@@ -29,7 +29,7 @@ The ``idrac`` hardware type supports the following Ironic interfaces:
 
 * `BIOS Interface`_: BIOS management
 * `Inspect Interface`_: Hardware inspection
-* Management Interface: Boot device management
+* `Management Interface`_: Boot device and firmware management
 * Power Interface: Power management
 * `RAID Interface`_: RAID controller and disk management
 * `Vendor Interface`_: BIOS management
@@ -265,6 +265,13 @@ The ``idrac-redfish`` inspect interface does not currently set ``pxe_enabled``
 on the ports. The user should ensure that ``pxe_enabled`` is set correctly on
 the ports following inspection with the ``idrac-redfish`` inspect interface.
 
+Management Interface
+====================
+
+The management interface for ``idrac-redfish`` supports updating firmware on
+nodes using a manual cleaning step.
+
+See :doc:`/admin/drivers/redfish` for more information on firmware update support.
 
 RAID Interface
 ==============
diff --git a/doc/source/admin/drivers/redfish.rst b/doc/source/admin/drivers/redfish.rst
index c2740452a..46f85644d 100644
--- a/doc/source/admin/drivers/redfish.rst
+++ b/doc/source/admin/drivers/redfish.rst
@@ -249,6 +249,136 @@ scenario.
 
   Make sure to use add the simple-init_ element when building the IPA ramdisk.
 
+Firmware update using manual cleaning step
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``redfish`` hardware type supports updating the firmware on nodes using a
+manual cleaning step.
+
+The firmware update cleaning step allows one or more firmware updates to be
+applied to a node. If multiple updates are specified, then they are applied
+sequentially in the order given. The server is rebooted once per update.
+If a failure occurs, the cleaning step immediately fails which may result
+in some updates not being applied. If the node is placed into maintenance
+mode while a firmware update cleaning step is running that is performing
+multiple firmware updates, the update in progress will complete, and processing
+of the remaining updates will pause.  When the node is taken out of maintenance
+mode, processing of the remaining updates will continue.
+
+When updating the BMC firmware, the BMC may become unavailable for a period of
+time as it resets. In this case, it may be desireable to have the cleaning step
+wait after the update has been applied before indicating that the
+update was successful. This allows the BMC time to fully reset before further
+operations are carried out against it. To cause the cleaning step to wait after
+applying an update, an optional ``wait`` argument may be specified in the
+firmware image dictionary. The value of this argument indicates the number of
+seconds to wait following the update. If the ``wait`` argument is not
+specified, then this is equivalent to ``wait 0``, meaning that it will not
+wait and immediately proceed with the next firmware update if there is one,
+or complete the cleaning step if not.
+
+The ``update_firmware`` cleaning step accepts JSON in the following format::
+
+    [{
+        "interface": "management",
+        "step": "update_firmware",
+        "args": {
+            "firmware_images":[
+                {
+                    "url": "<url_to_firmware_image1>",
+                    "wait": <number_of_seconds_to_wait>
+                },
+                {
+                    "url": "<url_to_firmware_image2>"
+                },
+                ...
+            ]
+        }
+    }]
+
+The different attributes of the ``update_firmware`` cleaning step are as follows:
+
+.. csv-table::
+    :header: "Attribute", "Description"
+    :widths: 30, 120
+
+    "``interface``", "Interface of the cleaning step.  Must be ``management`` for firmware update"
+    "``step``", "Name of cleaning step.  Must be ``update_firmware`` for firmware update"
+    "``args``", "Keyword-argument entry (<name>: <value>) being passed to cleaning step"
+    "``args.firmware_images``", "Ordered list of dictionaries of firmware images to be applied"
+
+Each firmware image dictionary, is of the form::
+
+    {
+      "url": "<URL of firmware image file>",
+      "wait": <Optional time in seconds to wait after applying update>
+    }
+
+The ``url`` argument in the firmware image dictionary is mandatory, while the
+``wait`` argument is optional.
+
+
+.. note::
+   Only ``http`` and ``https`` URLs are currently supported in the ``url``
+   argument.
+
+.. note::
+   At the present time, targets for the firmware update cannot be specified.
+   In testing, the BMC applied the update to all applicable targets on the
+   node. It is assumed that the BMC knows what components a given firmware
+   image is applicable to.
+
+To perform a firmware update, first download the firmware to a web server that
+the BMC has network access to. This could be the ironic conductor web server
+or another web server on the BMC network. Using a web browser, curl, or similar
+tool on a server that has network access to the BMC, try downloading
+the firmware to verify that the URLs are correct and that the web server is
+configured properly.
+
+Next, construct the JSON for the firmware update cleaning step to be executed.
+When launching the firmware update, the JSON may be specified on the command
+line directly or in a file. The following
+example shows one cleaning step that installs two firmware updates. The first
+updates the BMC firmware followed by a five minute wait to allow the BMC time
+to start back up. The second updates the firmware on all applicable NICs.::
+
+    [{
+        "interface": "management",
+        "step": "update_firmware",
+        "args": {
+            "firmware_images":[
+                {
+                    "url": "http://192.0.2.10/BMC_4_22_00_00.EXE",
+                    "wait": 300
+                },
+                {
+                    "url": "https://192.0.2.10/NIC_19.0.12_A00.EXE"
+                }
+            ]
+        }
+    }]
+
+Finally, launch the firmware update cleaning step against the node. The
+following example assumes the above JSON is in a file named
+``firmware_update.json``::
+
+    openstack baremetal node clean <ironic_node_uuid> --clean-steps firmware_update.json
+
+In the following example, the JSON is specified directly on the command line::
+
+    openstack baremetal node clean <ironic_node_uuid> --clean-steps '[{"interface": "management", "step": "update_firmware", "args": {"firmware_images":[{"url": "http://192.0.2.10/BMC_4_22_00_00.EXE", "wait": 300}, {"url": "https://192.0.2.10/NIC_19.0.12_A00.EXE"}]}}]'
+
+.. note::
+   Firmware updates may take some time to complete. If a firmware update
+   cleaning step consistently times out, then consider performing fewer
+   firmware updates in the cleaning step or increasing
+   ``clean_callback_timeout`` in ironic.conf to increase the timeout value.
+
+.. warning::
+   Warning: Removing power from a server while it is in the process of updating
+   firmware may result in devices in the server, or the server itself becoming
+   inoperable.
+
 .. _Redfish: http://redfish.dmtf.org/
 .. _Sushy: https://opendev.org/openstack/sushy
 .. _TLS: https://en.wikipedia.org/wiki/Transport_Layer_Security