f6191f2969
The doc8 linter found several syntax problems in our docs; primarily a large number of places we used single-backticks to surround something when we should've used double-backticks. This is frontrunning a change that will add these checks to CI. Change-Id: Ib23b5728c072f2008cb3b19e9fb7192ee5d82413
290 lines
12 KiB
ReStructuredText
290 lines
12 KiB
ReStructuredText
Firmware update using manual cleaning
|
|
=====================================
|
|
|
|
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.
|
|
|
|
.. note:: Only :doc:`/admin/drivers/redfish` supports firmware updates
|
|
currently.
|
|
|
|
When updating the BMC firmware, the BMC may become unavailable for a period of
|
|
time as it resets. In this case, it may be desirable 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.
|
|
|
|
How it works - via Management Interface
|
|
---------------------------------------
|
|
|
|
The ``update_firmware`` cleaning step accepts JSON in the following format::
|
|
|
|
[{
|
|
"interface": "management",
|
|
"step": "update_firmware",
|
|
"args": {
|
|
"firmware_images":[
|
|
{
|
|
"url": "<url_to_firmware_image1>",
|
|
"checksum": "<checksum for image, uses SHA1, SHA256, or SHA512>",
|
|
"source": "<optional override source setting for image>",
|
|
"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 the 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>",
|
|
"checksum": "<checksum for image, uses SHA1>",
|
|
"source": "<Optional override source setting for image>",
|
|
"wait": <Optional time in seconds to wait after applying update>
|
|
}
|
|
|
|
The ``url`` and ``checksum`` arguments in the firmware image dictionary are
|
|
mandatory, while the ``source`` and ``wait`` arguments are optional.
|
|
|
|
For ``url`` currently ``http``, ``https``, ``swift`` and ``file`` schemes are
|
|
supported.
|
|
|
|
``source`` corresponds to :oslo.config:option:`redfish.firmware_source` and by
|
|
setting it here, it is possible to override global setting per firmware image
|
|
in clean step arguments.
|
|
|
|
.. 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.
|
|
|
|
Applying updates
|
|
----------------
|
|
|
|
To perform a firmware update, first download the firmware to a web server,
|
|
Swift or filesystem that the Ironic conductor or 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 or Ironic conductor, 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 four firmware updates. All except 3rd entry that has explicit
|
|
``source`` added, uses setting from :oslo.config:option:`redfish.firmware_source` to determine
|
|
if and where to stage the files:
|
|
|
|
.. code-block:: json
|
|
|
|
[{
|
|
"interface": "management",
|
|
"step": "update_firmware",
|
|
"args": {
|
|
"firmware_images":[
|
|
{
|
|
"url": "http://192.0.2.10/BMC_4_22_00_00.EXE",
|
|
"checksum": "<sha1-checksum-of-the-file>",
|
|
"wait": 300
|
|
},
|
|
{
|
|
"url": "https://192.0.2.10/NIC_19.0.12_A00.EXE",
|
|
"checksum": "<sha1-checksum-of-the-file>"
|
|
},
|
|
{
|
|
"url": "file:///firmware_images/idrac/9/PERC_WN64_6.65.65.65_A00.EXE",
|
|
"checksum": "<sha1-checksum-of-the-file>",
|
|
"source": "http"
|
|
},
|
|
{
|
|
"url": "swift://firmware_container/BIOS_W8Y0W_WN64_2.1.7.EXE",
|
|
"checksum": "<sha1-checksum-of-the-file>"
|
|
}
|
|
]
|
|
}
|
|
}]
|
|
|
|
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``:
|
|
|
|
.. code-block:: console
|
|
|
|
$ baremetal node clean <ironic_node_uuid> --clean-steps firmware_update.json
|
|
|
|
In the following example, the JSON is specified directly on the command line:
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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.
|
|
|
|
How it works - via Firmware Interface
|
|
-------------------------------------
|
|
|
|
The ``update`` step can be used via cleaning or servicing, it accepts a JSON in
|
|
the following format::
|
|
|
|
[{
|
|
"interface": "firmware",
|
|
"step": "update",
|
|
"args": {
|
|
"settings":[
|
|
{
|
|
"component": "bmc"
|
|
"url": "<url_to_firmware_image1>"
|
|
"wait": <number_of_seconds_to_wait>
|
|
},
|
|
{
|
|
"component": "bios"
|
|
"url": "<url_to_firmware_image2>"
|
|
},
|
|
...
|
|
]
|
|
}
|
|
}]
|
|
|
|
The different attributes of the ``update`` step are as follows:
|
|
|
|
.. csv-table::
|
|
:header: "Attribute", "Description"
|
|
:widths: 30, 120
|
|
|
|
"``interface``", "Interface of the step. Must be ``firmware`` for firmware update"
|
|
"``step``", "Name of the step. Must be ``update`` for firmware update"
|
|
"``args``", "Keyword-argument entry (<name>: <value>) being passed to the step"
|
|
"``args.settings``", "Ordered list of dictionaries of firmware updates to be applied"
|
|
|
|
Each firmware image dictionary, is of the form::
|
|
|
|
{
|
|
"component": "The desired component to have the firmware updated, only bios and bmc are currently supported",
|
|
"url": "<URL of firmware image file>",
|
|
"wait": <Optional time in seconds to wait after applying update>
|
|
}
|
|
|
|
The ``component`` and ``url`` arguments in the firmware image dictionary are
|
|
mandatory, while the ``wait`` argument is optional.
|
|
|
|
For ``url`` currently ``http``, ``https``, ``swift`` and ``file`` schemes are
|
|
supported.
|
|
|
|
|
|
Applying updates
|
|
----------------
|
|
|
|
To perform a firmware update, first download the firmware to a web server,
|
|
Swift or filesystem that the Ironic conductor or 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 or Ironic conductor, 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 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 step that
|
|
installs two firmware updates.
|
|
|
|
.. code-block:: json
|
|
|
|
[{
|
|
"interface": "firmware",
|
|
"step": "update",
|
|
"args": {
|
|
"settings":[
|
|
{
|
|
"component": "bmc",
|
|
"url": "http://192.0.2.10/BMC_4_22_00_00.EXE",
|
|
"wait": 300
|
|
},
|
|
{
|
|
"component": "bios",
|
|
"url": "https://192.0.2.10/BIOS_19.0.12_A00.EXE"
|
|
},
|
|
|
|
]
|
|
}
|
|
}]
|
|
|
|
|
|
It is also possible to use ``runbooks`` for firmware updates.
|
|
|
|
.. code-block:: console
|
|
|
|
$ baremetal runbook create --name <RUNBOOK> --steps \
|
|
'[{"interface": "firmware", "step": "update", "args": {"settings":[{"component": "bmc", "url":"http://192.168.0.8:8080/ilo5278.bin"}]}}]'
|
|
$ baremetal node add trait <ironic_node_uuid> <RUNBOOK>
|
|
$ baremetal node <clean or service> <ironic_node_uuid> --runbook <RUNBOOK>
|
|
|
|
Finally, launch the firmware update step against the node. The
|
|
following example assumes the above JSON is in a file named
|
|
``update.json``:
|
|
|
|
.. code-block:: console
|
|
|
|
$ baremetal node clean <ironic_node_uuid> --clean-steps update.json
|
|
$ baremetal node service <ironic_node_uuid> --service-steps update.json
|
|
|
|
In the following example, the JSON is specified directly on the command line:
|
|
|
|
.. code-block:: console
|
|
|
|
$ baremetal node clean <ironic_node_uuid> --clean-steps \
|
|
'[{"interface": "firmware", "step": "update", "args": {"settings":[{"component": "bmc", "url":"http://192.168.0.8:8080/ilo5278.bin"}]}}]'
|
|
$ baremetal node clean <ironic_node_uuid> --clean-steps \
|
|
'[{"interface": "firmware", "step": "update", "args": {"settings":[{"component": "bios", "url":"http://192.168.0.8:8080/bios.bin"}]}}]'
|
|
$ baremetal node service <ironic_node_uuid> --service-steps \
|
|
'[{"interface": "firmware", "step": "update", "args": {"settings":[{"component": "bmc", "url":"http://192.168.0.8:8080/ilo5278.bin"}]}}]'
|
|
$ baremetal node service <ironic_node_uuid> --service-steps \
|
|
'[{"interface": "firmware", "step": "update", "args": {"settings":[{"component": "bios", "url":"http://192.168.0.8:8080/bios.bin"}]}}]'
|
|
|
|
.. note::
|
|
For Dell machines you must extract the firmimgFIT.d9 from the iDRAC.exe
|
|
This can be done using the command ``7za e iDRAC_<VERSION>.exe``.
|
|
|
|
.. note::
|
|
For HPE machines you must extract the ilo5_<version>.bin from the
|
|
ilo5_<version>.fwpkg
|
|
This can be done using the command ``7za e ilo<version>.fwpkg``.
|