Document BIOS and firmware upgrade on BMHs using Redfish.

User story: As an operator I want to install specific versions of firmware in my machines before installing the Operating System.

Section to update: IPI on Bare Metal > Configuring the BIOS

SME: Iury Gregory Melo Ferreira
QE: Jad Haj Yahya

Implementation: (copied from  Firmware interface proposal)
This needs to be confirmed with SME because it might be out of date.

This proposes a new Custom Resource Definition (CRD) to store the information about the firmware components from Ironic. The initial version stores only the firmware information about BMC and BIOS, we may expand this to other components in the future. The new CRD is named HostFirmwareComponents and will consist of the following:

• components - the current firmware components and their information, retrieved from Ironic via the Firmware API will be stored in the Status section.
• updates - firmware components to be updated via Ironic will be stored in the Spec section. It will be empty when the CRD is created.

The firmware components are retrieved from the BMC by Ironic and cached whenever the node moves to manageable or cleaning, or when the components are updated. The BMO manages the data as follows:

• The node first transitions to manageable during the Registering state, so at the end of that state components will be populated.
• Firmware components can be updated during the Preparing state, so at the end of that state the components will also be retrieved and used to update components.

A user can update updates to specify the desired firmware of each component. The BMO will detect changes on it by comparing the name/url pairs to the values in Status. When a change is detected, the BMO will add the new values to the Ironic clean-steps API in the Preparing state, when building the manual clean steps, the Host will re-enter this state from Ready/Available state whenever its config differs from the last stored one.

After executing the cleaning, Ironic will re-read the information about the firmware components and cache them, the new information can be retrieved by the BMO and used to update components.

If the update fails we won’t keep trying to reconcile, the BMO will put the node in a FirmwareUpdateError state. We will allow deletion of the BMH when in this state. When in FirmwareUpdateError state the following actions can be executed:

• BMH can be moved to Preparing state again, this can be done by deleting updates from the spec in the CRD, or changing the urls in it. This will trigger another manual cleaning.
• BMH can be moved to Deleting state.

An example of the resource before applying:

---
apiVersion: metal3.io/v1alpha1
kind: HostFirmwareComponents
metadata:
  namespace: host3firmwarecomponents.metal3.io
spec:
  updates:
  - name: bios
    url: https://myurl.with.firmware.for.bios
  - name: bmc
    url: https://myurl.with.firmware.for.bmc
status:
  components:
  - component: bios
    initialVersion: "v1.0.0"
    currentVersion: "v1.0.0"
    lastVersionFlashed: null
    updatedAt: null
  - component: bmc
    initialVersion: "v1.0.5"
    currentVersion: "v1.0.5"
    lastVersionFlashed: null
    updatedAt: null
  lastUpdated: "2023-10-13T13:34:06Z" 

Example of the Resource after applied:

---
apiVersion: metal3.io/v1alpha1
kind: HostFirmwareComponents
metadata:
  namespace: host3firmwarecomponents.metal3.io
spec:
  updates:
  - name: bios
    url: https://myurl.with.firmware.for.bios
  - name: bmc
    url: https://myurl.with.firmware.for.bmc
status:
  components:
  - component: bios
    initialVersion: "v1.0.0"
    currentVersion: "v1.5.0"
    lastVersionFlashed: "v1.5.0"
    updatedAt: "2023-10-13T13:50:06Z"
  - component: bmc
    initialVersion: "v1.0.5"
    currentVersion: "v1.2.0"
    lastVersionFlashed: "v1.2.0"
    updatedAt: "2023-10-13T13:50:06Z"
  updates:
  - name: bios
    url: https://myurl.with.firmware.for.bios
  - name: bmc
    url: https://myurl.with.firmware.for.bmc
  lastUpdated: "2023-10-13T13:50:06Z" 

Fields Description * component: the name of the firmware component

• initialVersion: the initial firmware version of the component, Ironic retrieves this information when creating the BMH and it can't be changed.
• currentVersion: the current firmware version of the component, initially the value will match the one in initialVersion, unless there was a firmware update for the BMH.
• lastVersionFlashed: the last firmware version of the component that was flashed in the BMH, this field will only have a value when a firmware update is executed.
• updatedAt: when the firmware component information was updated by Ironic.

Risks and Mitigations

• In case of failure when executing the firmware update, BMO will put the BMH in a failed state.
• New firmware may have fixed a few bugs, but it can also introduce new ones. We will try to mitigate this by providing some versions of tested firmware when possible.