Skip to content

Commit 9aa6607

Browse files
johnwilkinsjohnwilkins
committed
HCIDOCS-201: Added firmware components..
1 parent 8ab7ce3 commit 9aa6607

8 files changed

+304
-9
lines changed

‎images/715_OpenShift_Bare_Metal_Operator_updates_0624.png

115 KB
Loading

‎modules/bmo-about-the-bare-metal-operator.adoc

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,16 @@
88

99
Use the Bare Metal Operator (BMO) to provision, manage, and inspect bare-metal hosts in your cluster.
1010

11-
The BMO uses three resources to complete these tasks:
11+
The BMO uses the following resources to complete these tasks:
1212

1313
* `BareMetalHost`
1414
* `HostFirmwareSettings`
1515
* `FirmwareSchema`
16+
* `HostFirmwareComponents`
1617
1718
The BMO maintains an inventory of the physical hosts in the cluster by mapping each bare-metal host to an instance of the `BareMetalHost` custom resource definition. Each `BareMetalHost` resource features hardware, software, and firmware details. The BMO continually inspects the bare-metal hosts in the cluster to ensure each `BareMetalHost` resource accurately details the components of the corresponding host.
1819

19-
The BMO also uses the `HostFirmwareSettings` resource and the `FirmwareSchema` resource to detail firmware specifications for the bare-metal host.
20+
The BMO also uses the `HostFirmwareSettings` resource, the `FirmwareSchema` resource, and the `HostFirmwareComponents` resource to detail firmware specifications and upgrade or downgrade firmware for the bare-metal host.
2021

2122
The BMO interfaces with bare-metal hosts in the cluster by using the Ironic API service. The Ironic service uses the Baseboard Management Controller (BMC) on the host to interface with the machine.
2223

@@ -26,4 +27,5 @@ Some common tasks you can complete by using the BMO include the following:
2627
* Format a host's disk contents before provisioning or after deprovisioning
2728
* Turn on or off a host
2829
* Change firmware settings
29-
* View the host's hardware details
30+
* View the host's hardware details
31+
* Upgrade or downgrade a host's firmware to a specific version

‎modules/bmo-about-the-baremetalhost-resource.adoc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ image:
7171
checksumType:
7272
format:
7373
----
74-
a| The `image` configuration setting holds the details for the image to be deployed on the host. Ironic requires the image fields. However, when the `externallyProvisioned` configuration setting is set to `true` and the external management doesn't require power control, the fields can be empty. The fields are:
74+
a| The `image` configuration setting holds the details for the image to be deployed on the host. Ironic requires the image fields. However, when the `externallyProvisioned` configuration setting is set to `true` and the external management does not require power control, the fields can be empty. The setting supports the following fields:
7575

7676
* `url`: The URL of an image to deploy to the host.
7777
* `checksum`: The actual checksum or a URL to a file containing the checksum for the image at `image.url`.
@@ -104,7 +104,7 @@ a| (Optional) Contains the information about the RAID configuration for bare me
104104

105105
See the following configuration settings:
106106

107-
* `hardwareRAIDVolumes`: Contains the list of logical drives for hardware RAID, and defines the desired volume configuration in the hardware RAID. If you don't specify `rootDeviceHints`, the first volume is the root volume. The sub-fields are:
107+
* `hardwareRAIDVolumes`: Contains the list of logical drives for hardware RAID, and defines the desired volume configuration in the hardware RAID. If you do not specify `rootDeviceHints`, the first volume is the root volume. The sub-fields are:
108108

109109
** `level`: The RAID level for the logical drive. The following levels are supported: `0`,`1`,`2`,`5`,`6`,`1+0`,`5+0`,`6+0`.
110110
** `name`: The name of the volume as a string. It should be unique within the server. If not specified, the volume name will be auto-generated.
@@ -114,7 +114,7 @@ See the following configuration settings:
114114
** `rotational`: If set to `true`, it will only select rotational disk drives. If set to `false`, it will only select solid-state and NVMe drives. If not set, it selects any drive types, which is the default behavior.
115115
** `sizeGibibytes`: The size of the logical drive as an integer to create in GiB. If unspecified or set to `0`, it will use the maximum capacity of physical drive for the logical drive.
116116

117-
* `softwareRAIDVolumes`: {product-title} {product-version} does not support software RAID. The following information is for reference only. This configuration contains the list of logical disks for software RAID. If you don't specify `rootDeviceHints`, the first volume is the root volume. If you set `HardwareRAIDVolumes`, this item will be invalid. Software RAIDs will always be deleted. The number of created software RAID devices must be `1` or `2`. If there is only one software RAID device, it must be `RAID-1`. If there are two RAID devices, the first device must be `RAID-1`, while the RAID level for the second device can be `0`, `1`, or `1+0`. The first RAID device will be the deployment device. Therefore, enforcing `RAID-1` reduces the risk of a non-booting node in case of a device failure. The `softwareRAIDVolume` field defines the desired configuration of the volume in the software RAID. The sub-fields are:
117+
* `softwareRAIDVolumes`: {product-title} {product-version} does not support software RAID. The following information is for reference only. This configuration contains the list of logical disks for software RAID. If you do not specify `rootDeviceHints`, the first volume is the root volume. If you set `HardwareRAIDVolumes`, this item will be invalid. Software RAIDs will always be deleted. The number of created software RAID devices must be `1` or `2`. If there is only one software RAID device, it must be `RAID-1`. If there are two RAID devices, the first device must be `RAID-1`, while the RAID level for the second device can be `0`, `1`, or `1+0`. The first RAID device will be the deployment device. Therefore, enforcing `RAID-1` reduces the risk of a non-booting node in case of a device failure. The `softwareRAIDVolume` field defines the desired configuration of the volume in the software RAID. The sub-fields are:
118118

119119
** `level`: The RAID level for the logical drive. The following levels are supported: `0`,`1`,`1+0`.
120120
** `physicalDisks`: A list of device hints. The number of items should be greater than or equal to `2`.

‎modules/bmo-about-the-hostfirmwarecomponents-resource.adoc

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
// This is included in the following assemblies:
2+
//
3+
// post_installation_configuration/bare-metal-configuration.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="about-the-hostfirmwarecomponents-resource_{context}"]
7+
= About the HostFirmwareComponents resource
8+
9+
Metal^3^ provides the `HostFirmwareComponents` resource, which describes BIOS and baseboard management controller (BMC) firmware versions. The `HostFirmwareComponents` resource contains two sections:
10+
11+
. The `HostFirmwareComponents` spec
12+
. The `HostFirmwareComponents` status
13+
14+
== HostFirmwareComponents spec
15+
16+
The `spec` section of the `HostFirmwareComponents` resource defines the desired state of the host's BIOS and BMC versions.
17+
18+
.HostFirmwareComponents spec
19+
[options="header"]
20+
|====
21+
|Parameters |Description
22+
23+
a|
24+
----
25+
updates:
26+
component:
27+
url:
28+
----
29+
a| The `updates` configuration setting contains the components to update. The fields are:
30+
31+
* `component`: The name of the component. The valid settings are `bios` or `bmc`.
32+
33+
* `url`: The URL to the component's firmware specification and version.
34+
|====
35+
36+
37+
== HostFirmwareComponents status
38+
39+
The `status` section of the `HostFirmwareComponents` resource returns the current status of the host's BIOS and BMC versions.
40+
41+
.HostFirmwareComponents status
42+
[options="header"]
43+
|====
44+
|Parameters |Description
45+
46+
a|
47+
----
48+
components:
49+
component:
50+
initialVersion:
51+
currentVersion:
52+
lastVersionFlashed:
53+
updatedAt:
54+
----
55+
a| The `components` section contains the status of the components. The fields are:
56+
57+
* `component`: The name of the firmware component. It returns `bios` or `bmc`.
58+
59+
* `initialVersion`: The initial firmware version of the component. Ironic retrieves this information when creating the `BareMetalHost` resource. You cannot change it.
60+
61+
* `currentVersion`: The current firmware version of the component. Initially, the value matches the `initialVersion` value until Ironic updates the firmware on the bare-metal host.
62+
63+
* `lastVersionFlashed`: The last firmware version of the component flashed on the bare-metal host. This field returns `null` until Ironic updates the firmware.
64+
65+
* `updatedAt`: The timestamp when Ironic updated the bare-metal host's firmware.
66+
67+
a|
68+
----
69+
updates:
70+
component:
71+
url:
72+
----
73+
a| The `updates` configuration setting contains the updated components. The fields are:
74+
75+
* `component`: The name of the component.
76+
77+
* `url`: The URL to the component's firmware specification and version.
78+
|====

‎modules/bmo-editing-the-hostfirmwarecomponents-resource.adoc

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
// This is included in the following assemblies:
2+
//
3+
// post_installation_configuration/bare-metal-configuration.adoc
4+
5+
[id="editing-the-hostfirmwarecomponents-resource_{context}"]
6+
= Editing the HostFirmwareComponents resource
7+
8+
You can edit the `HostFirmwareComponents` resource of a node.
9+
10+
.Procedure
11+
12+
. Get the detailed list of `HostFirmwareComponents` resources:
13+
+
14+
[source,terminal]
15+
----
16+
$ oc get hostfirmwarecomponents -n openshift-machine-api -o yaml
17+
----
18+
19+
. Edit a host's `HostFirmwareComponents` resource:
20+
+
21+
[source,terminal]
22+
----
23+
$ oc edit <host_name> hostfirmwarecomponents -n openshift-machine-api <1>
24+
----
25+
<1> Where `<host_name>` is the name of the host. The `HostFirmwareComponents` resource will open in the default editor for your terminal.
26+
+
27+
.Example output
28+
[source,yaml]
29+
----
30+
---
31+
apiVersion: metal3.io/v1alpha1
32+
kind: HostFirmwareComponents
33+
metadata:
34+
creationTimestamp: 2024-04-25T20:32:06Z"
35+
generation: 1
36+
name: ostest-master-2
37+
namespace: openshift-machine-api
38+
ownerReferences:
39+
- apiVersion: metal3.io/v1alpha1
40+
blockOwnerDeletion: true
41+
controller: true
42+
kind: BareMetalHost
43+
name: ostest-master-2
44+
uid: 16022566-7850-4dc8-9e7d-f216211d4195
45+
resourceVersion: "2437"
46+
uid: 2038d63f-afc0-4413-8ffe-2f8e098d1f6c
47+
spec:
48+
updates:
49+
- name: bios <1>
50+
url: https://myurl.with.firmware.for.bios <2>
51+
- name: bmc <3>
52+
url: https://myurl.with.firmware.for.bmc <4>
53+
status:
54+
components:
55+
- component: bios
56+
currentVersion: 1.0.0
57+
initialVersion: 1.0.0
58+
- component: bmc
59+
currentVersion: "1.00"
60+
initialVersion: "1.00"
61+
conditions:
62+
- lastTransitionTime: "2024-04-25T20:32:06Z"
63+
message: ""
64+
observedGeneration: 1
65+
reason: OK
66+
status: "True"
67+
type: Valid
68+
- lastTransitionTime: "2024-04-25T20:32:06Z"
69+
message: ""
70+
observedGeneration: 1
71+
reason: OK
72+
status: "False"
73+
type: ChangeDetected
74+
lastUpdated: "2024-04-25T20:32:06Z"
75+
----
76+
<1> To set a BIOS version, set the `name` attribute to `bios`.
77+
<2> To set a BIOS version, set the `url` attribute to the URL for the firmware version of the BIOS.
78+
<3> To set a BMC version, set the `name` attribute to `bmc`.
79+
<4> To set a BMC version, set the `url` attribute to the URL for the firmware verison of the BMC.
80+
81+
. Save the changes and exit the editor.
82+
83+
. Get the host’s machine name:
84+
+
85+
[source,terminal]
86+
----
87+
$ oc get bmh <host_name> -n openshift-machine name <1>
88+
----
89+
<1> Where `<host_name>` is the name of the host. The machine name appears under the `CONSUMER` field.
90+
91+
. Annotate the machine to delete it from the machine set:
92+
+
93+
[source,terminal]
94+
----
95+
$ oc annotate machine <machine_name> machine.openshift.io/delete-machine=true -n openshift-machine-api <1>
96+
----
97+
<1> Where `<machine_name>` is the name of the machine to delete.
98+
99+
. Get a list of nodes and count the number of worker nodes:
100+
+
101+
[source,terminal]
102+
----
103+
$ oc get nodes
104+
----
105+
106+
. Get the machine set:
107+
+
108+
[source,terminal]
109+
----
110+
$ oc get machinesets -n openshift-machine-api
111+
----
112+
113+
. Scale the machine set:
114+
+
115+
[source,terminal]
116+
----
117+
$ oc scale machineset <machineset_name> -n openshift-machine-api --replicas=<n-1> <1>
118+
----
119+
<1> Where `<machineset_name>` is the name of the machine set and `<n-1>` is the decremented number of worker nodes.
120+
121+
. When the host enters the `Available` state, scale up the machine set to make the `HostFirmwareComponents` resource changes take effect:
122+
+
123+
[source,terminal]
124+
----
125+
$ oc scale machineset <machineset_name> -n openshift-machine-api --replicas=<n> <1>
126+
----
127+
<1> Where `<machineset_name>` is the name of the machine set and `<n>` is the number of worker nodes.

‎modules/bmo-getting-the-hostfirmwarecomponents-resource.adoc

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
// This is included in the following assemblies:
2+
//
3+
// post_installation_configuration/bare-metal-configuration.adoc
4+
5+
[id="getting-the-hostfirmwarecomponents-resource_{context}"]
6+
= Getting the HostFirmwareComponents resource
7+
8+
The `HostFirmwareComponents` resource contains the specific firmware version of the BIOS and baseboard management controller (BMC) of a physical host. You must get the `HostFirmwareComponents` resource for a physical host to review the firmware version and status.
9+
10+
.Procedure
11+
12+
. Get the detailed list of `HostFirmwareComponents` resources:
13+
+
14+
[source,terminal]
15+
----
16+
$ oc get hostfirmwarecomponents -n openshift-machine-api -o yaml
17+
----
18+
19+
. Get the list of `HostFirmwareComponents` resources:
20+
+
21+
[source,terminal]
22+
----
23+
$ oc get hostfirmwarecomponents -n openshift-machine-api
24+
----
25+
26+
. Get the `HostFirmwareComponents` resource for a particular host:
27+
+
28+
[source,terminal]
29+
----
30+
$ oc get hostfirmwarecomponents <host_name> -n openshift-machine-api -o yaml
31+
----
32+
+
33+
Where `<host_name>` is the name of the host.
34+
+
35+
.Example output
36+
[source,yaml]
37+
----
38+
---
39+
apiVersion: metal3.io/v1alpha1
40+
kind: HostFirmwareComponents
41+
metadata:
42+
creationTimestamp: 2024-04-25T20:32:06Z"
43+
generation: 1
44+
name: ostest-master-2
45+
namespace: openshift-machine-api
46+
ownerReferences:
47+
- apiVersion: metal3.io/v1alpha1
48+
blockOwnerDeletion: true
49+
controller: true
50+
kind: BareMetalHost
51+
name: ostest-master-2
52+
uid: 16022566-7850-4dc8-9e7d-f216211d4195
53+
resourceVersion: "2437"
54+
uid: 2038d63f-afc0-4413-8ffe-2f8e098d1f6c
55+
spec:
56+
updates: []
57+
status:
58+
components:
59+
- component: bios
60+
currentVersion: 1.0.0
61+
initialVersion: 1.0.0
62+
- component: bmc
63+
currentVersion: "1.00"
64+
initialVersion: "1.00"
65+
conditions:
66+
- lastTransitionTime: "2024-04-25T20:32:06Z"
67+
message: ""
68+
observedGeneration: 1
69+
reason: OK
70+
status: "True"
71+
type: Valid
72+
- lastTransitionTime: "2024-04-25T20:32:06Z"
73+
message: ""
74+
observedGeneration: 1
75+
reason: OK
76+
status: "False"
77+
type: ChangeDetected
78+
lastUpdated: "2024-04-25T20:32:06Z"
79+
updates: []
80+
----

‎modules/con_bmo-bare-metal-operator-architecture.adoc

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@
55
[id="bmo-bare-metal-operator-architecture_{context}"]
66
= Bare Metal Operator architecture
77

8-
The Bare Metal Operator (BMO) uses three resources to provision, manage, and inspect bare-metal hosts in your cluster. The following diagram illustrates the architecture of these resources:
8+
The Bare Metal Operator (BMO) uses the following resources to provision, manage, and inspect bare-metal hosts in your cluster. The following diagram illustrates the architecture of these resources:
99

10-
image::302_OpenShift_Bare_Metal_Operator_0223.png[BMO architecture overview]
10+
image::715_OpenShift_Bare_Metal_Operator_updates_0624.png[BMO architecture overview]
1111

1212
.BareMetalHost
1313

@@ -42,7 +42,11 @@ Firmware settings vary among hardware vendors and host models. A `FirmwareSchema
4242

4343
A `FirmwareSchema` resource can apply to many `BareMetalHost` resources if the schema is the same.
4444

45+
.HostFirmwareComponents
46+
47+
Metal^3^ provides the `HostFirmwareComponents` resource, which describes BIOS and baseboard management controller (BMC) firmware versions. You can upgrade or downgrade the host's firmware to a specific version by editing the `spec` field of the `HostFirmwareComponents` resource. This is useful when deploying with validated patterns that have been tested against specific firmware versions.
48+
4549
[role="_additional-resources"]
4650
.Additional resources
47-
* link:https://metal3.io/[Metal³ API service for provisioning bare-metal hosts]
51+
* link:https://metal3.io/[Metal^3^ API service for provisioning bare-metal hosts]
4852
* link:https://ironicbaremetal.org/[Ironic API service for managing bare-metal infrastructure]

‎post_installation_configuration/bare-metal-configuration.adoc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,7 @@ include::modules/bmo-verifying-the-hostfirmware-settings-resource-is-valid.adoc[
2020

2121
include::modules/bmo-about-the-firmwareschema-resource.adoc[leveloffset=+1]
2222
include::modules/bmo-getting-the-firmwareschema-resource.adoc[leveloffset=+1]
23+
24+
include::modules/bmo-about-the-hostfirmwarecomponents-resource.adoc[leveloffset=+1]
25+
include::modules/bmo-getting-the-hostfirmwarecomponents-resource.adoc[leveloffset=+1]
26+
include::modules/bmo-editing-the-hostfirmwarecomponents-resource.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)