openstack/ironic
Code Issues Proposed changes

Decompose the Redfish documentation

Browse Source 
This page is huge and keeps growing. So:
* Move additional topics to sub-documents.
* Move ESP creation to the install guide (it's not even
  Redfish-specific).
* Create a generic firmware updates document.

Provide a feature listing at the top for easier navigation.

Change-Id: Ic58c139da5e1e60f5ce4d2cec18972ebee9e2485
This commit is contained in:
Dmitry Tantsur 2024-06-12 11:49:53 +02:00
parent d0a833095a
commit 95784428a4
No known key found for this signature in database
GPG Key ID: 315B2AF9FD216C60
9 changed files with 436 additions and 397 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/admin/drivers/ilo.rst
View File

@ -2051,7 +2051,7 @@ Events subscription
^^^^^^^^^^^^^^^^^^^
Events subscription is supported by ``ilo`` and ``ilo5`` hardware types with
``ilo`` vendor interface for Gen10 and Gen10 Plus servers. See
:ref:`node-vendor-passthru-methods` for more information.
:doc:`redfish/passthru` for more information.
Anaconda based deployment
^^^^^^^^^^^^^^^^^^^^^^^^^

441
doc/source/admin/drivers/redfish.rst
View File

@ -6,7 +6,25 @@ Overview
========
The ``redfish`` driver enables managing servers compliant with the
Redfish_ protocol.
Redfish_ protocol. Supported features include:
* Network, :ref:`virtual media <redfish-virtual-media>` and :ref:`HTTP(s)
<redfish-https-boot>` boot.
* Additional virtual media features:
* :ref:`Ramdisk deploy interface <redfish-virtual-media-ramdisk>`.
* :doc:`/admin/dhcp-less`.
* `Virtual media API
<https://docs.openstack.org/api-ref/baremetal/#attach-detach-virtual-media-nodes>`_.
* :ref:`Changing boot mode and secure boot status <redfish-boot-mode>`.
* :doc:`In-band </admin/inspection/index>` and `out-of-band inspection`_.
* Retrieving and changing :ref:`BIOS settings <redfish-bios-settings>`.
* Applying :doc:`firmware updates </admin/firmware-updates>`.
* Configuring :doc:`hardware RAID </admin/raid>`.
* Hardware metrics and integration with `ironic-prometheus-exporter
<https://docs.openstack.org/ironic-prometheus-exporter/latest/>`_.
* Event notifications configured via :doc:`redfish/passthru`.
Prerequisites
=============
@ -115,6 +133,8 @@ a node with the ``redfish`` driver. For example:
For more information about enrolling nodes see :ref:`enrollment`
in the install guide.
.. _redfish-boot-mode:
Boot mode support
=================
@ -157,26 +177,6 @@ end, the previous power state is restored.
This logic makes changing boot configuration more robust at the expense of
several reboots in the worst case.
Out-Of-Band inspection
======================
The ``redfish`` hardware type can inspect the bare metal node by querying
Redfish compatible BMC. This process is quick and reliable compared to the
way the ``inspector`` hardware type works i.e. booting bare metal node
into the introspection ramdisk.
.. note::
The ``redfish`` inspect interface relies on the optional parts of the
Redfish specification. Not all Redfish-compliant BMCs might serve the
required information, in which case bare metal node inspection will fail.
.. note::
The ``local_gb`` property cannot always be discovered, for example, when a
node does not have local storage or the Redfish implementation does not
support the required schema. In this case the property will be set to 0.
.. _redfish-virtual-media:
Virtual media boot
@ -215,7 +215,7 @@ BIOS boot mode, it suffice to set ironic boot interface to
:doc:`/admin/drivers/idrac` for more details on this hardware type.
If UEFI boot mode is desired, the user should additionally supply EFI
System Partition image (ESP_), see `Configuring an ESP image`_ for details.
System Partition image (ESP_), see :doc:`/install/configure-esp` for details.
If ``[driver_info]/config_via_floppy`` boolean property of the node is set to
``true``, ironic will create a file with runtime configuration parameters,
@ -271,80 +271,9 @@ with the Wallaby release it's possible to provide a pre-built ISO image:
for backward compatibility.
No customization is currently done to the image, so e.g.
:doc:`/admin/dhcp-less` won't work. `Configuring an ESP image`_ is also
:doc:`/admin/dhcp-less` won't work. :doc:`/install/configure-esp` is also
unnecessary.
Configuring an ESP image
~~~~~~~~~~~~~~~~~~~~~~~~~
An ESP image is an image that contains the necessary bootloader to boot the ISO
in UEFI mode. You will need a GRUB2 image file, as well as Shim for secure
boot. See :ref:`uefi-pxe-grub` for an explanation how to get them.
Then the following script can be used to build an ESP image:
.. code-block:: bash
DEST=/path/to/esp.img
GRUB2=/path/to/grub.efi
SHIM=/path/to/shim.efi
dd if=/dev/zero of=$DEST bs=4096 count=1024
mkfs.msdos -F 12 -n ESP_IMAGE $DEST
# The following commands require mtools to be installed
mmd -i $DEST EFI EFI/BOOT
mcopy -i $DEST -v $SHIM ::EFI/BOOT/BOOTX64.efi
mcopy -i $DEST -v $GRUB2 ::EFI/BOOT/GRUBX64.efi
mdir -i $DEST ::EFI/BOOT
.. note::
If you use an architecture other than x86-64, you'll need to adjust the
destination paths.
.. warning::
If you are using secure boot, you *must* utilize the same SHIM and GRUB
binaries matching your distribution's kernel and ramdisk, otherwise the
Secure Boot "chain of trust" will be broken.
Additionally, if you encounter odd issues UEFI booting with virtual media
which point to the bootloader, verify the appropriate distribution matching
binaries are in use.
The resulting image should be provided via the ``driver_info/bootloader``
ironic node property in form of an image UUID or a URL:
.. code-block:: bash
baremetal node set --driver-info bootloader=<glance-uuid-or-url> node-0
Alternatively, set the bootloader UUID or URL in the configuration file:
.. code-block:: ini
[conductor]
bootloader = <glance-uuid-or-url>
Finally, you need to provide the correct GRUB2 configuration path for your
image. In most cases this path will depend on your distribution, more
precisely, the distribution you took the GRUB2 image from. For example:
CentOS:
.. code-block:: ini
[DEFAULT]
grub_config_path = EFI/centos/grub.cfg
Ubuntu:
.. code-block:: ini
[DEFAULT]
grub_config_path = EFI/ubuntu/grub.cfg
.. note::
Unlike in the script above, these paths are case-sensitive!
.. _redfish-virtual-media-ramdisk:
Virtual Media Ramdisk
@ -388,11 +317,7 @@ or via a link to a raw image:
baremetal node deploy <node name or UUID> \
--config-drive http://example.com/config.img
Layer 3 or DHCP-less ramdisk booting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DHCP-less deploy is supported by the Redfish virtual media boot. See
:doc:`/admin/dhcp-less` for more information.
.. _redfish-https-boot:
Redfish HTTP(s) Boot
====================
@ -422,7 +347,7 @@ where the node should boot from.
Like the ``redfish-virtual-media`` boot interface, you will need
to create an EFI System Partition image (ESP_), see
`Configuring an ESP image`_ for details on how to do this.
:doc:`/install/configure-esp` for details on how to do this.
Additionally, if you would like to use the ``ramdisk`` deployment
interface, the same basic instructions covered in `Virtual Media Ramdisk`_
@ -444,154 +369,27 @@ the files locally in the ``[deploy]http_root`` folder structure, and then
generate a URL pointing the BMC to connect to the HTTP service configured
via ``[deploy]http_url``.
Firmware update using manual cleaning
=====================================
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 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.
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 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>",
"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 ``[redfish]firmware_source`` and by setting it here,
it is possible to override global setting per firmware image in clean step
arguments.
Out-Of-Band inspection
======================
The ``redfish`` hardware type can inspect the bare metal node by querying
Redfish compatible BMC. This process is quick and reliable compared to the
way the ``inspector`` hardware type works i.e. booting bare metal node
into the introspection ramdisk.
.. 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,
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 ``[redfish]firmware_source`` to determine
if and where to stage the files::
[{
"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``::
baremetal node clean <ironic_node_uuid> --clean-steps firmware_update.json
In the following example, the JSON is specified directly on the command line::
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"}]}}]'
The ``redfish`` inspect interface relies on the optional parts of the
Redfish specification. Not all Redfish-compliant BMCs might serve the
required information, in which case bare metal node inspection will fail.
.. 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.
The ``local_gb`` property cannot always be discovered, for example, when a
node does not have local storage or the Redfish implementation does not
support the required schema. In this case the property will be set to 0.
.. _redfish-bios-settings:
Retrieving BIOS Settings
========================
@ -617,163 +415,14 @@ settings. The following fields will be returned in the BIOS API
"``unique``", "The setting is specific to this node"
"``reset_required``", "After changing this setting a node reboot is required"
.. _node-vendor-passthru-methods:
Further topics
==============
Node Vendor Passthru Methods
============================
.. csv-table::
:header: "Method", "Description"
:widths: 25, 120
"``create_subscription``", "Create a new subscription on the Node"
"``delete_subscription``", "Delete a subscription of a Node"
"``get_all_subscriptions``", "List all subscriptions of a Node"
"``get_subscription``", "Show a single subscription of a Node"
"``eject_vmedia``", "Eject attached virtual media from a Node"
Create Subscription
~~~~~~~~~~~~~~~~~~~
.. csv-table:: Request
:header: "Name", "In", "Type", "Description"
:widths: 25, 15, 15, 90
"Destination", "body", "string", "The URI of the destination Event Service"
"EventTypes (optional)", "body", "array", "List of types of events that shall be sent to the destination"
"Context (optional)", "body", "string", "A client-supplied string that is stored with the event destination
subscription"
"Protocol (optional)", "body", "string", "The protocol type that the event will use for sending
the event to the destination"
Example JSON to use in ``create_subscription``::
{
"Destination": "https://someurl",
"EventTypes": ["Alert"],
"Context": "MyProtocol",
"args": "Redfish"
}
Delete Subscription
~~~~~~~~~~~~~~~~~~~
.. csv-table:: Request
:header: "Name", "In", "Type", "Description"
:widths: 21, 21, 21, 37
"id", "body", "string", "The Id of the subscription generated by the BMC "
Example JSON to use in ``delete_subscription``::
{
"id": "<id of the subscription generated by the BMC>"
}
Get Subscription
~~~~~~~~~~~~~~~~
.. csv-table:: Request
:header: "Name", "In", "Type", "Description"
:widths: 21, 21, 21, 37
"id", "body", "string", "The Id of the subscription generated by the BMC "
Example JSON to use in ``get_subscription``::
{
"id": "<id of the subscription generated by the BMC>"
}
Get All Subscriptions
~~~~~~~~~~~~~~~~~~~~~
The ``get_all_subscriptions`` doesn't require any parameters.
Eject Virtual Media
~~~~~~~~~~~~~~~~~~~
.. csv-table:: Request
:header: "Name", "In", "Type", "Description"
:widths: 25, 15, 15, 90
"boot_device (optional)", "body", "string", "Type of the device to eject (all devices by default)"
Internal Session Cache
======================
The ``redfish`` hardware type, and derived interfaces, utilizes a built-in
session cache which prevents Ironic from re-authenticating every time
Ironic attempts to connect to the BMC for any reason.
This consists of cached connectors objects which are used and tracked by
a unique consideration of ``redfish_username``, ``redfish_password``,
``redfish_verify_ca``, and finally ``redfish_address``. Changing any one
of those values will trigger a new session to be created.
The ``redfish_system_id`` value is explicitly not considered as Redfish
has a model of use of one BMC to many systems, which is also a model
Ironic supports.
The session cache default size is ``1000`` sessions per conductor.
If you are operating a deployment with a larger number of Redfish
BMCs, it is advised that you do appropriately tune that number.
This can be tuned via the API service configuration file,
``[redfish]connection_cache_size``.
Session Cache Expiration
~~~~~~~~~~~~~~~~~~~~~~~~
By default, sessions remain cached for as long as possible in
memory, as long as they have not experienced an authentication,
connection, or other unexplained error.
Under normal circumstances, the sessions will only be rolled out
of the cache in order of oldest first when the cache becomes full.
There is no time based expiration to entries in the session cache.
Of course, the cache is only in memory, and restarting the
``ironic-conductor`` will also cause the cache to be rebuilt
from scratch. If this is due to any persistent connectivity issue,
this may be sign of an unexpected condition, and please consider
contacting the Ironic developer community for assistance.
Redfish Interoperability Profile
================================
Ironic projects provides Redfish Interoperability Profile located in
``redfish-interop-profiles`` folder at source code root. The Redfish
Interoperability Profile is a JSON document written in a particular format
that serves two purposes.
* It enables the creation of a human-readable document that merges the
profile requirements with the Redfish schema into a single document
for developers or users.
* It allows a conformance test utility to test a Redfish Service
implementation for conformance with the profile.
The JSON document structure is intended to align easily with JSON payloads
retrieved from Redfish Service implementations, to allow for easy comparisons
and conformance testing. Many of the properties defined within this structure
have assumed default values that correspond with the most common use case, so
that those properties can be omitted from the document for brevity.
Validation of Profiles using DMTF tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An open source utility has been created by the Redfish Forum to verify that
a Redfish Service implementation conforms to the requirements included in a
Redfish Interoperability Profile. The Redfish Interop Validator is available
for download from the DMTF's organization on Github at
https://github.com/DMTF/Redfish-Interop-Validator. Refer to instructions in
README on how to configure and run validation.
.. toctree::
redfish/passthru
redfish/session-cache
redfish/interop
.. _Redfish: http://redfish.dmtf.org/
.. _Sushy: https://opendev.org/openstack/sushy

30
doc/source/admin/drivers/redfish/interop.rst Normal file
View File

@ -0,0 +1,30 @@
Redfish Interoperability Profile
================================
The Ironic project provides a Redfish Interoperability Profile located in
``redfish-interop-profiles`` folder at source code root. The Redfish
Interoperability Profile is a JSON document written in a particular format
that serves two purposes:
* It enables the creation of a human-readable document that merges the
profile requirements with the Redfish schema into a single document
for developers or users.
* It allows a conformance test utility to test a Redfish Service
implementation for conformance with the profile.
The JSON document structure is intended to align easily with JSON payloads
retrieved from Redfish Service implementations, to allow for easy comparisons
and conformance testing. Many of the properties defined within this structure
have assumed default values that correspond with the most common use case, so
that those properties can be omitted from the document for brevity.
Validation of Profiles using DMTF tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An open source utility has been created by the Redfish Forum to verify that
a Redfish Service implementation conforms to the requirements included in a
Redfish Interoperability Profile. The Redfish Interop Validator is available
for download from the DMTF's organization on Github at
https://github.com/DMTF/Redfish-Interop-Validator. Refer to instructions in
README on how to configure and run validation.

87
doc/source/admin/drivers/redfish/passthru.rst Normal file
View File

@ -0,0 +1,87 @@
Node Vendor Passthru Methods
============================
.. csv-table::
:header: "Method", "Description"
:widths: 25, 120
"``create_subscription``", "Create a new subscription on the Node"
"``delete_subscription``", "Delete a subscription of a Node"
"``get_all_subscriptions``", "List all subscriptions of a Node"
"``get_subscription``", "Show a single subscription of a Node"
"``eject_vmedia``", "Eject attached virtual media from a Node"
Create Subscription
~~~~~~~~~~~~~~~~~~~
.. csv-table:: Request
:header: "Name", "In", "Type", "Description"
:widths: 25, 15, 15, 90
"Destination", "body", "string", "The URI of the destination Event Service"
"EventTypes (optional)", "body", "array", "List of types of events that shall be sent to the destination"
"Context (optional)", "body", "string", "A client-supplied string that is stored with the event destination
subscription"
"Protocol (optional)", "body", "string", "The protocol type that the event will use for sending
the event to the destination"
Example JSON to use in ``create_subscription``::
{
"Destination": "https://someurl",
"EventTypes": ["Alert"],
"Context": "MyProtocol",
"args": "Redfish"
}
Delete Subscription
~~~~~~~~~~~~~~~~~~~
.. csv-table:: Request
:header: "Name", "In", "Type", "Description"
:widths: 21, 21, 21, 37
"id", "body", "string", "The Id of the subscription generated by the BMC "
Example JSON to use in ``delete_subscription``::
{
"id": "<id of the subscription generated by the BMC>"
}
Get Subscription
~~~~~~~~~~~~~~~~
.. csv-table:: Request
:header: "Name", "In", "Type", "Description"
:widths: 21, 21, 21, 37
"id", "body", "string", "The Id of the subscription generated by the BMC "
Example JSON to use in ``get_subscription``::
{
"id": "<id of the subscription generated by the BMC>"
}
Get All Subscriptions
~~~~~~~~~~~~~~~~~~~~~
The ``get_all_subscriptions`` doesn't require any parameters.
Eject Virtual Media
~~~~~~~~~~~~~~~~~~~
.. csv-table:: Request
:header: "Name", "In", "Type", "Description"
:widths: 25, 15, 15, 90
"boot_device (optional)", "body", "string", "Type of the device to eject (all devices by default)"

38
doc/source/admin/drivers/redfish/session-cache.rst Normal file
View File

@ -0,0 +1,38 @@
Internal Session Cache
======================
The ``redfish`` hardware type, and derived interfaces, utilizes a built-in
session cache which prevents Ironic from re-authenticating every time
Ironic attempts to connect to the BMC for any reason.
This consists of cached connectors objects which are used and tracked by
a unique consideration of ``redfish_username``, ``redfish_password``,
``redfish_verify_ca``, and finally ``redfish_address``. Changing any one
of those values will trigger a new session to be created.
The ``redfish_system_id`` value is explicitly not considered as Redfish
has a model of use of one BMC to many systems, which is also a model
Ironic supports.
The session cache default size is ``1000`` sessions per conductor.
If you are operating a deployment with a larger number of Redfish
BMCs, it is advised that you do appropriately tune that number.
This can be tuned via the API service configuration file,
``[redfish]connection_cache_size``.
Session Cache Expiration
~~~~~~~~~~~~~~~~~~~~~~~~
By default, sessions remain cached for as long as possible in
memory, as long as they have not experienced an authentication,
connection, or other unexplained error.
Under normal circumstances, the sessions will only be rolled out
of the cache in order of oldest first when the cache becomes full.
There is no time based expiration to entries in the session cache.
Of course, the cache is only in memory, and restarting the
``ironic-conductor`` will also cause the cache to be rebuilt
from scratch. If this is due to any persistent connectivity issue,
this may be sign of an unexpected condition, and please consider
contacting the Ironic developer community for assistance.

160
doc/source/admin/firmware-updates.rst Normal file
View File

@ -0,0 +1,160 @@
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
------------
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 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>",
"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 ``[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.

1
doc/source/admin/index.rst
View File

@ -16,6 +16,7 @@ the services.
Node Retirement <retirement>
RAID Configuration <raid>
BIOS Settings <bios>
Firmware Updates <firmware-updates>
Node Rescuing <rescue>
Configuring to boot from volume <boot-from-volume>
Multi-tenant Networking <multitenancy>

73
doc/source/install/configure-esp.rst Normal file
View File

@ -0,0 +1,73 @@
Configuring an ESP image
========================
An ESP_ image is an image that contains the necessary bootloader to boot the
ISO in UEFI mode. You will need a GRUB2 image file, as well as Shim_ for secure
boot. See :ref:`uefi-pxe-grub` for an explanation how to get them.
Then the following script can be used to build an ESP image:
.. code-block:: bash
DEST=/path/to/esp.img
GRUB2=/path/to/grub.efi
SHIM=/path/to/shim.efi
dd if=/dev/zero of=$DEST bs=4096 count=1024
mkfs.msdos -F 12 -n ESP_IMAGE $DEST
# The following commands require mtools to be installed
mmd -i $DEST EFI EFI/BOOT
mcopy -i $DEST -v $SHIM ::EFI/BOOT/BOOTX64.efi
mcopy -i $DEST -v $GRUB2 ::EFI/BOOT/GRUBX64.efi
mdir -i $DEST ::EFI/BOOT
.. note::
If you use an architecture other than x86-64, you'll need to adjust the
destination paths.
.. warning::
If you are using secure boot, you *must* utilize the same SHIM and GRUB
binaries matching your distribution's kernel and ramdisk, otherwise the
Secure Boot "chain of trust" will be broken.
Additionally, if you encounter odd issues UEFI booting with virtual media
which point to the bootloader, verify the appropriate distribution matching
binaries are in use.
The resulting image should be provided via the ``driver_info/bootloader``
ironic node property in form of an image UUID or a URL:
.. code-block:: bash
baremetal node set --driver-info bootloader=<glance-uuid-or-url> node-0
Alternatively, set the bootloader UUID or URL in the configuration file:
.. code-block:: ini
[conductor]
bootloader = <glance-uuid-or-url>
Finally, you need to provide the correct GRUB2 configuration path for your
image. In most cases this path will depend on your distribution, more
precisely, the distribution you took the GRUB2 image from. For example:
CentOS:
.. code-block:: ini
[DEFAULT]
grub_config_path = EFI/centos/grub.cfg
Ubuntu:
.. code-block:: ini
[DEFAULT]
grub_config_path = EFI/ubuntu/grub.cfg
.. note::
Unlike in the script above, these paths are case-sensitive!
.. _ESP: https://wiki.ubuntu.com/EFIBootLoaders#Booting_from_EFI
.. _Shim: https://github.com/rhboot/shim

1
doc/source/install/setup-drivers.rst
View File

@ -7,3 +7,4 @@ Set up the drivers for the Bare Metal service
enabling-drivers
configure-pxe
configure-ipmi
configure-esp