Skip to content

Commit 7b25ecf

Browse files
aireillyaireilly
authored
Merge pull request #81426 from aireilly/TELCODOCS-336-ztp-bios
TELCODOCS-336 - firmware settings updates via GitOps ZTP
2 parents e54e381 + 07f9372 commit 7b25ecf

5 files changed

+347
-0
lines changed

‎edge_computing/ztp-deploying-far-edge-sites.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,19 @@ include::modules/ztp-sno-siteconfig-config-reference.adoc[leveloffset=+2]
7171
7272
* xref:../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.adoc#root-device-hints_preparing-to-install-with-agent-based-installer[About root device hints]
7373
74+
include::modules/ztp-configuring-host-firmware-with-gitops-ztp.adoc[leveloffset=+1]
75+
76+
[role="_additional-resources"]
77+
.Additional resources
78+
79+
* xref:../edge_computing/ztp-vdu-validating-cluster-tuning.adoc#ztp-du-firmware-config-reference_vdu-config-ref[Recommended firmware configuration for vDU cluster hosts]
80+
81+
include::modules/ztp-retrieving-the-host-firmware-schema.adoc[leveloffset=+2]
82+
83+
include::modules/ztp-retrieving-the-host-firmware-settings.adoc[leveloffset=+2]
84+
85+
include::modules/ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp.adoc[leveloffset=+2]
86+
7487
include::modules/ztp-monitoring-installation-progress.adoc[leveloffset=+1]
7588

7689
include::modules/ztp-troubleshooting-ztp-gitops-installation-crs.adoc[leveloffset=+1]

‎modules/ztp-configuring-host-firmware-with-gitops-ztp.adoc

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * edge_computing/ztp-deploying-far-edge-sites.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="ztp-configuring-host-firmware-with-gitops-ztp_{context}"]
7+
= Managing host firmware settings with {ztp}
8+
9+
Hosts require the correct firmware configuration to ensure high performance and optimal efficiency.
10+
You can deploy custom host firmware configurations for managed clusters with {ztp}.
11+
12+
Tune hosts with specific hardware profiles in your lab and ensure they are optimized for your requirements.
13+
When you have completed host tuning to your satisfaction, you extract the host profile and save it in your {ztp} repository.
14+
Then, you use the host profile to configure firmware settings in the managed cluster hosts that you deploy with {ztp}.
15+
16+
You specify the required hardware profiles in `SiteConfig` custom resources (CRs) that you use to deploy the managed clusters.
17+
The {ztp} pipeline generates the required `HostFirmwareSettings` (`HFS`) and `BareMetalHost` (`BMH`) CRs that are applied to the hub cluster.
18+
19+
Use the following best practices to manage your host firmware profiles.
20+
21+
Identify critical firmware settings with hardware vendors::
22+
Work with hardware vendors to identify and document critical host firmware settings required for optimal performance and compatibility with the deployed host platform.
23+
24+
Use common firmware configurations across similar hardware platforms::
25+
Where possible, use a standardized host firmware configuration across similar hardware platforms to reduce complexity and potential errors during deployment.
26+
27+
Test firmware configurations in a lab environment::
28+
Test host firmware configurations in a controlled lab environment before deploying in production to ensure that settings are compatible with hardware, firmware, and software.
29+
30+
Manage firmware profiles in source control::
31+
Manage host firmware profiles in Git repositories to track changes, ensure consistency, and facilitate collaboration with vendors.

‎modules/ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp.adoc

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * edge_computing/ztp-deploying-far-edge-sites.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp_{context}"]
7+
= Deploying user-defined firmware to cluster hosts with {ztp}
8+
9+
You can deploy user-defined firmware settings to cluster hosts by configuring the `SiteConfig` custom resource (CR) to include a hardware profile that you want to apply during cluster host provisioning.
10+
You can configure hardware profiles to apply to hosts in the following scenarios:
11+
12+
* All hosts site-wide
13+
* Only cluster hosts that meet certain criteria
14+
* Individual cluster hosts
15+
16+
[IMPORTANT]
17+
====
18+
You can configure host hardware profiles to be applied in a hierarchy.
19+
Cluster-level settings override site-wide settings.
20+
Node level profiles override cluster and site-wide settings.
21+
====
22+
23+
.Prerequisites
24+
25+
* You have installed the OpenShift CLI (`oc`).
26+
27+
* You have installed {rh-rhacm-first} and logged in to the hub cluster as a user with `cluster-admin` privileges.
28+
29+
* You have provisioned a cluster that is managed by {rh-rhacm}.
30+
31+
* You created a Git repository where you manage your custom site configuration data.
32+
The repository must be accessible from the hub cluster and be defined as a source repository for the Argo CD application.
33+
34+
.Procedure
35+
36+
. Create the host firmware profile that contain the firmware settings you want to apply.
37+
For example, create the following YAML file:
38+
+
39+
.host-firmware.profile
40+
[source,yaml]
41+
----
42+
BootMode: Uefi
43+
LogicalProc: Enabled
44+
ProcVirtualization: Enabled
45+
----
46+
47+
. Save the hardware profile YAML file relative to the `kustomization.yaml` file that you use to define how to provision the cluster, for example:
48+
+
49+
[source,terminal]
50+
----
51+
example-ztp/install
52+
└── site-install
53+
├── siteconfig-example.yaml
54+
├── kustomization.yaml
55+
└── host-firmware.profile
56+
----
57+
58+
. Edit the `SiteConfig` CR to include the firmware profile that you want to apply in the cluster.
59+
For example:
60+
+
61+
[source,yaml]
62+
----
63+
apiVersion: ran.openshift.io/v1
64+
kind: SiteConfig
65+
metadata:
66+
name: "site-plan-cluster"
67+
namespace: "example-cluster-namespace"
68+
spec:
69+
baseDomain: "example.com"
70+
# ...
71+
biosConfigRef:
72+
filePath: "./host-firmware.profile" <1>
73+
----
74+
<1> Applies the hardware profile to all cluster hosts site-wide
75+
76+
+
77+
[NOTE]
78+
====
79+
Where possible, use a single `SiteConfig` CR per cluster.
80+
====
81+
82+
. Optional. To apply a hardware profile to hosts in a specific cluster, update `clusters.biosConfigRef.filePath` with the hardware profile that you want to apply.
83+
For example:
84+
+
85+
[source,yaml]
86+
----
87+
clusters:
88+
- clusterName: "cluster-1"
89+
# ...
90+
biosConfigRef:
91+
filePath: "./host-firmware.profile" <1>
92+
----
93+
<1> Applies to all hosts in the `cluster-1` cluster
94+
95+
. Optional. To apply a hardware profile to a specific host in the cluster, update `clusters.nodes.biosConfigRef.filePath` with the hardware profile that you want to apply.
96+
For example:
97+
+
98+
[source,yaml]
99+
----
100+
clusters:
101+
- clusterName: "cluster-1"
102+
# ...
103+
nodes:
104+
- hostName: "compute-1.example.com"
105+
# ...
106+
bootMode: "UEFI"
107+
biosConfigRef:
108+
filePath: "./host-firmware.profile" <1>
109+
----
110+
<1> Applies the firmware profile to the `compute-1.example.com` host in the cluster
111+
112+
. Commit the `SiteConfig` CR and associated `kustomization.yaml` changes in your Git repository and push the changes.
113+
+
114+
The ArgoCD pipeline detects the changes and begins the managed cluster deployment.
115+
+
116+
[NOTE]
117+
====
118+
Cluster deployment proceeds even if an invalid firmware setting is detected.
119+
To apply a correction using {ztp}, re-deploy the cluster with the corrected hardware profile.
120+
====
121+
122+
.Verification
123+
124+
* Check that the firmware settings have been applied in the managed cluster host.
125+
For example, run the following command:
126+
+
127+
[source,terminal]
128+
----
129+
$ oc get hfs -n <managed_cluster_namespace> <managed_cluster_name> -o jsonpath='{.status.conditions[?(@.type=="Valid")].status}'
130+
----
131+
+
132+
.Example output
133+
[source,terminal]
134+
----
135+
True
136+
----

‎modules/ztp-retrieving-the-host-firmware-schema.adoc

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * edge_computing/ztp-deploying-far-edge-sites.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ztp-retrieving-the-host-firmware-schema_{context}"]
7+
= Retrieving the host firmware schema for a managed cluster
8+
9+
You can discover the host firmware schema for managed clusters.
10+
The host firmware schema for bare-metal hosts is populated with information that the Ironic API returns.
11+
The API returns information about host firmware interfaces, including firmware setting types, allowable values, ranges, and flags.
12+
13+
.Prerequisites
14+
15+
* You have installed the OpenShift CLI (`oc`).
16+
17+
* You have installed {rh-rhacm-first} and logged in to the hub cluster as a user with `cluster-admin` privileges.
18+
19+
* You have provisioned a cluster that is managed by {rh-rhacm}.
20+
21+
.Procedure
22+
23+
* Discover the host firmware schema for the managed cluster.
24+
Run the following command:
25+
+
26+
[source,terminal]
27+
----
28+
$ oc get firmwareschema -n <managed_cluster_namespace> -o yaml
29+
----
30+
+
31+
.Example output
32+
[source,terminal]
33+
----
34+
apiVersion: v1
35+
items:
36+
- apiVersion: metal3.io/v1alpha1
37+
kind: FirmwareSchema
38+
metadata:
39+
creationTimestamp: "2024-09-11T10:29:43Z"
40+
generation: 1
41+
name: schema-40562318
42+
namespace: compute-1
43+
ownerReferences:
44+
- apiVersion: metal3.io/v1alpha1
45+
kind: HostFirmwareSettings
46+
name: compute-1.example.com
47+
uid: 65d0e89b-1cd8-4317-966d-2fbbbe033fe9
48+
resourceVersion: "280057624"
49+
uid: 511ad25d-f1c9-457b-9a96-776605c7b887
50+
spec:
51+
schema:
52+
AccessControlService:
53+
allowable_values:
54+
- Enabled
55+
- Disabled
56+
attribute_type: Enumeration
57+
read_only: false
58+
# ...
59+
----

‎modules/ztp-retrieving-the-host-firmware-settings.adoc

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * edge_computing/ztp-deploying-far-edge-sites.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ztp-retrieving-the-host-firmware-settings_{context}"]
7+
= Retrieving the host firmware settings for a managed cluster
8+
9+
You can retrieve the host firmware settings for managed clusters.
10+
This is useful when you have deployed changes to the host firmware and you want to monitor the changes and ensure that they are applied successfully.
11+
12+
.Prerequisites
13+
14+
* You have installed the OpenShift CLI (`oc`).
15+
16+
* You have installed {rh-rhacm-first} and logged in to the hub cluster as a user with `cluster-admin` privileges.
17+
18+
* You have provisioned a cluster that is managed by {rh-rhacm}.
19+
20+
.Procedure
21+
22+
. Retrieve the host firmware settings for the managed cluster.
23+
Run the following command:
24+
+
25+
--
26+
[source,terminal]
27+
----
28+
$ oc get hostfirmwaresettings -n <cluster_namespace> <node_name> -o yaml
29+
----
30+
31+
.Example output
32+
[source,terminal]
33+
----
34+
apiVersion: v1
35+
items:
36+
- apiVersion: metal3.io/v1alpha1
37+
kind: HostFirmwareSettings
38+
metadata:
39+
creationTimestamp: "2024-09-11T10:29:43Z"
40+
generation: 1
41+
name: compute-1.example.com
42+
namespace: kni-qe-24
43+
ownerReferences:
44+
- apiVersion: metal3.io/v1alpha1
45+
blockOwnerDeletion: true
46+
controller: true
47+
kind: BareMetalHost
48+
name: compute-1.example.com
49+
uid: 0baddbb7-bb34-4224-8427-3d01d91c9287
50+
resourceVersion: "280057626"
51+
uid: 65d0e89b-1cd8-4317-966d-2fbbbe033fe9
52+
spec:
53+
settings: {}
54+
status:
55+
conditions:
56+
- lastTransitionTime: "2024-09-11T10:29:43Z"
57+
message: ""
58+
observedGeneration: 1
59+
reason: Success
60+
status: "True" <1>
61+
type: ChangeDetected
62+
- lastTransitionTime: "2024-09-11T10:29:43Z"
63+
message: Invalid BIOS setting
64+
observedGeneration: 1
65+
reason: ConfigurationError
66+
status: "False" <2>
67+
type: Valid
68+
lastUpdated: "2024-09-11T10:29:43Z"
69+
schema:
70+
name: schema-40562318
71+
namespace: compute-1
72+
settings: <3>
73+
AccessControlService: Enabled
74+
AcpiHpet: Enabled
75+
AcpiRootBridgePxm: Enabled
76+
# ...
77+
----
78+
<1> Indicates that a change in the host firmware settings has been detected
79+
<2> Indicates that the host has an invalid firmware setting
80+
<3> The complete list of configured host firmware settings is returned under the `status.settings` field
81+
--
82+
83+
. Optional: Check the status of the `HostFirmwareSettings` (`hfs`) custom resource in the cluster:
84+
+
85+
[source,terminal]
86+
----
87+
$ oc get hfs -n <managed_cluster_namespace> <managed_cluster_name> -o jsonpath='{.status.conditions[?(@.type=="ChangeDetected")].status}'
88+
----
89+
+
90+
.Example output
91+
[source,terminal]
92+
----
93+
True
94+
----
95+
96+
. Optional: Check for invalid firmware settings in the cluster host.
97+
Run the following command:
98+
+
99+
[source,terminal]
100+
----
101+
$ oc get hfs -n <managed_cluster_namespace> <managed_cluster_name> -o jsonpath='{.status.conditions[?(@.type=="Valid")].status}'
102+
----
103+
+
104+
.Example output
105+
[source,terminal]
106+
----
107+
False
108+
----

0 commit comments

Comments
 (0)