diff --git a/doc/source/admin/drivers/ilo.rst b/doc/source/admin/drivers/ilo.rst index f65aa6538a..deed7c15bd 100644 --- a/doc/source/admin/drivers/ilo.rst +++ b/doc/source/admin/drivers/ilo.rst @@ -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 ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/admin/drivers/redfish.rst b/doc/source/admin/drivers/redfish.rst index 4989b591a3..609791adf3 100644 --- a/doc/source/admin/drivers/redfish.rst +++ b/doc/source/admin/drivers/redfish.rst @@ -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 ` and :ref:`HTTP(s) + ` boot. +* Additional virtual media features: + + * :ref:`Ramdisk deploy interface `. + * :doc:`/admin/dhcp-less`. + * `Virtual media API + `_. + +* :ref:`Changing boot mode and secure boot status `. +* :doc:`In-band ` and `out-of-band inspection`_. +* Retrieving and changing :ref:`BIOS settings `. +* Applying :doc:`firmware updates `. +* Configuring :doc:`hardware RAID `. +* Hardware metrics and integration with `ironic-prometheus-exporter + `_. +* 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= node-0 - -Alternatively, set the bootloader UUID or URL in the configuration file: - -.. code-block:: ini - - [conductor] - bootloader = - -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 \ --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": "", - "checksum": "", - "source": "", - "wait": - }, - { - "url": "" - }, - ... - ] - } - }] - -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 (: ) 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": "", - "checksum": "", - "source": "", - "wait": - } - -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": "", - "wait": 300 - }, - { - "url": "https://192.0.2.10/NIC_19.0.12_A00.EXE", - "checksum": "" - }, - { - "url": "file:///firmware_images/idrac/9/PERC_WN64_6.65.65.65_A00.EXE", - "checksum": "", - "source": "http" - }, - { - "url": "swift://firmware_container/BIOS_W8Y0W_WN64_2.1.7.EXE", - "checksum": "" - } - ] - } - }] - -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 --clean-steps firmware_update.json - -In the following example, the JSON is specified directly on the command line:: - - baremetal node clean --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": "" - } - - -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": "" - } - - -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 diff --git a/doc/source/admin/drivers/redfish/interop.rst b/doc/source/admin/drivers/redfish/interop.rst new file mode 100644 index 0000000000..fc21ef6e2a --- /dev/null +++ b/doc/source/admin/drivers/redfish/interop.rst @@ -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. + diff --git a/doc/source/admin/drivers/redfish/passthru.rst b/doc/source/admin/drivers/redfish/passthru.rst new file mode 100644 index 0000000000..575b916e24 --- /dev/null +++ b/doc/source/admin/drivers/redfish/passthru.rst @@ -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": "" + } + + +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": "" + } + + +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)" + diff --git a/doc/source/admin/drivers/redfish/session-cache.rst b/doc/source/admin/drivers/redfish/session-cache.rst new file mode 100644 index 0000000000..9f83c8db3c --- /dev/null +++ b/doc/source/admin/drivers/redfish/session-cache.rst @@ -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. + diff --git a/doc/source/admin/firmware-updates.rst b/doc/source/admin/firmware-updates.rst new file mode 100644 index 0000000000..b0752edeaa --- /dev/null +++ b/doc/source/admin/firmware-updates.rst @@ -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": "", + "checksum": "", + "source": "", + "wait": + }, + { + "url": "" + }, + ... + ] + } + }] + +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 (: ) 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": "", + "checksum": "", + "source": "", + "wait": + } + +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": "", + "wait": 300 + }, + { + "url": "https://192.0.2.10/NIC_19.0.12_A00.EXE", + "checksum": "" + }, + { + "url": "file:///firmware_images/idrac/9/PERC_WN64_6.65.65.65_A00.EXE", + "checksum": "", + "source": "http" + }, + { + "url": "swift://firmware_container/BIOS_W8Y0W_WN64_2.1.7.EXE", + "checksum": "" + } + ] + } + }] + +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 --clean-steps firmware_update.json + +In the following example, the JSON is specified directly on the command line: + +.. code-block:: console + + $ baremetal node clean --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. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 236d0a26ee..3a19d2394d 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -16,6 +16,7 @@ the services. Node Retirement RAID Configuration BIOS Settings + Firmware Updates Node Rescuing Configuring to boot from volume Multi-tenant Networking diff --git a/doc/source/install/configure-esp.rst b/doc/source/install/configure-esp.rst new file mode 100644 index 0000000000..3196b88bf4 --- /dev/null +++ b/doc/source/install/configure-esp.rst @@ -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= node-0 + +Alternatively, set the bootloader UUID or URL in the configuration file: + +.. code-block:: ini + + [conductor] + bootloader = + +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 diff --git a/doc/source/install/setup-drivers.rst b/doc/source/install/setup-drivers.rst index 8e69b52d6b..68e1c63284 100644 --- a/doc/source/install/setup-drivers.rst +++ b/doc/source/install/setup-drivers.rst @@ -7,3 +7,4 @@ Set up the drivers for the Bare Metal service enabling-drivers configure-pxe configure-ipmi + configure-esp