[enterprise-4.17] TELCODOCS-336 - firmware settings updates via GitOps ZTP

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

@@ -71,6 +71,19 @@ include::modules/ztp-sno-siteconfig-config-reference.adoc[leveloffset=+2]
 
 * 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]
 
+include::modules/ztp-configuring-host-firmware-with-gitops-ztp.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../edge_computing/ztp-vdu-validating-cluster-tuning.adoc#ztp-du-firmware-config-reference_vdu-config-ref[Recommended firmware configuration for vDU cluster hosts]
+
+include::modules/ztp-retrieving-the-host-firmware-schema.adoc[leveloffset=+2]
+
+include::modules/ztp-retrieving-the-host-firmware-settings.adoc[leveloffset=+2]
+
+include::modules/ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp.adoc[leveloffset=+2]
+
 include::modules/ztp-monitoring-installation-progress.adoc[leveloffset=+1]
 
 include::modules/ztp-troubleshooting-ztp-gitops-installation-crs.adoc[leveloffset=+1]

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

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * edge_computing/ztp-deploying-far-edge-sites.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="ztp-configuring-host-firmware-with-gitops-ztp_{context}"]
+= Managing host firmware settings with {ztp}
+
+Hosts require the correct firmware configuration to ensure high performance and optimal efficiency.
+You can deploy custom host firmware configurations for managed clusters with {ztp}.
+
+Tune hosts with specific hardware profiles in your lab and ensure they are optimized for your requirements.
+When you have completed host tuning to your satisfaction, you extract the host profile and save it in your {ztp} repository.
+Then, you use the host profile to configure firmware settings in the managed cluster hosts that you deploy with {ztp}.
+
+You specify the required hardware profiles in `SiteConfig` custom resources (CRs) that you use to deploy the managed clusters.
+The {ztp} pipeline generates the required `HostFirmwareSettings` (`HFS`) and `BareMetalHost` (`BMH`) CRs that are applied to the hub cluster.
+
+Use the following best practices to manage your host firmware profiles.
+
+Identify critical firmware settings with hardware vendors::
+Work with hardware vendors to identify and document critical host firmware settings required for optimal performance and compatibility with the deployed host platform.
+
+Use common firmware configurations across similar hardware platforms::
+Where possible, use a standardized host firmware configuration across similar hardware platforms to reduce complexity and potential errors during deployment.
+
+Test firmware configurations in a lab environment::
+Test host firmware configurations in a controlled lab environment before deploying in production to ensure that settings are compatible with hardware, firmware, and software.
+
+Manage firmware profiles in source control::
+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

@@ -0,0 +1,136 @@
+// Module included in the following assemblies:
+//
+// * edge_computing/ztp-deploying-far-edge-sites.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp_{context}"]
+= Deploying user-defined firmware to cluster hosts with {ztp}
+
+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.
+You can configure hardware profiles to apply to hosts in the following scenarios:
+
+* All hosts site-wide
+* Only cluster hosts that meet certain criteria
+* Individual cluster hosts
+
+[IMPORTANT]
+====
+You can configure host hardware profiles to be applied in a hierarchy.
+Cluster-level settings override site-wide settings.
+Node level profiles override cluster and site-wide settings.
+====
+
+.Prerequisites
+
+* You have installed the OpenShift CLI (`oc`).
+
+* You have installed {rh-rhacm-first} and logged in to the hub cluster as a user with `cluster-admin` privileges.
+
+* You have provisioned a cluster that is managed by {rh-rhacm}.
+
+* You created a Git repository where you manage your custom site configuration data.
+The repository must be accessible from the hub cluster and be defined as a source repository for the Argo CD application.
+
+.Procedure
+
+. Create the host firmware profile that contain the firmware settings you want to apply.
+For example, create the following YAML file:
++
+.host-firmware.profile
+[source,yaml]
+----
+BootMode: Uefi
+LogicalProc: Enabled
+ProcVirtualization: Enabled
+----
+
+. Save the hardware profile YAML file relative to the `kustomization.yaml` file that you use to define how to provision the cluster, for example:
++
+[source,terminal]
+----
+example-ztp/install
+    └── site-install
+          ├── siteconfig-example.yaml
+          ├── kustomization.yaml
+          └── host-firmware.profile
+----
+
+. Edit the `SiteConfig` CR to include the firmware profile that you want to apply in the cluster.
+For example:
++
+[source,yaml]
+----
+apiVersion: ran.openshift.io/v1
+kind: SiteConfig
+metadata:
+  name: "site-plan-cluster"
+  namespace: "example-cluster-namespace"
+spec:
+  baseDomain: "example.com"
+  # ...
+  biosConfigRef:
+    filePath: "./host-firmware.profile" <1>
+----
+<1> Applies the hardware profile to all cluster hosts site-wide
+
++
+[NOTE]
+====
+Where possible, use a single `SiteConfig` CR per cluster.
+====
+
+. 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.
+For example:
++
+[source,yaml]
+----
+clusters:
+  - clusterName: "cluster-1"
+    # ...
+    biosConfigRef:
+      filePath: "./host-firmware.profile" <1>
+----
+<1> Applies to all hosts in the `cluster-1` cluster
+
+. 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.
+For example:
++
+[source,yaml]
+----
+clusters:
+  - clusterName: "cluster-1"
+    # ...
+    nodes:
+      - hostName: "compute-1.example.com"
+        # ...
+        bootMode: "UEFI"
+        biosConfigRef:
+          filePath: "./host-firmware.profile" <1>
+----
+<1> Applies the firmware profile to the `compute-1.example.com` host in the cluster
+
+. Commit the `SiteConfig` CR and associated `kustomization.yaml` changes in your Git repository and push the changes.
++
+The ArgoCD pipeline detects the changes and begins the managed cluster deployment.
++
+[NOTE]
+====
+Cluster deployment proceeds even if an invalid firmware setting is detected.
+To apply a correction using {ztp}, re-deploy the cluster with the corrected hardware profile.
+====
+
+.Verification
+
+* Check that the firmware settings have been applied in the managed cluster host.
+For example, run the following command:
++
+[source,terminal]
+----
+$ oc get hfs -n <managed_cluster_namespace> <managed_cluster_name> -o jsonpath='{.status.conditions[?(@.type=="Valid")].status}'
+----
++
+.Example output
+[source,terminal]
+----
+True
+----

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

@@ -0,0 +1,59 @@
+// Module included in the following assemblies:
+//
+// * edge_computing/ztp-deploying-far-edge-sites.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ztp-retrieving-the-host-firmware-schema_{context}"]
+= Retrieving the host firmware schema for a managed cluster
+
+You can discover the host firmware schema for managed clusters.
+The host firmware schema for bare-metal hosts is populated with information that the Ironic API returns.
+The API returns information about host firmware interfaces, including firmware setting types, allowable values, ranges, and flags.
+
+.Prerequisites
+
+* You have installed the OpenShift CLI (`oc`).
+
+* You have installed {rh-rhacm-first} and logged in to the hub cluster as a user with `cluster-admin` privileges.
+
+* You have provisioned a cluster that is managed by {rh-rhacm}.
+
+.Procedure
+
+* Discover the host firmware schema for the managed cluster.
+Run the following command:
++
+[source,terminal]
+----
+$ oc get firmwareschema -n <managed_cluster_namespace> -o yaml
+----
++
+.Example output
+[source,terminal]
+----
+apiVersion: v1
+items:
+- apiVersion: metal3.io/v1alpha1
+  kind: FirmwareSchema
+  metadata:
+    creationTimestamp: "2024-09-11T10:29:43Z"
+    generation: 1
+    name: schema-40562318
+    namespace: compute-1
+    ownerReferences:
+    - apiVersion: metal3.io/v1alpha1
+      kind: HostFirmwareSettings
+      name: compute-1.example.com
+      uid: 65d0e89b-1cd8-4317-966d-2fbbbe033fe9
+    resourceVersion: "280057624"
+    uid: 511ad25d-f1c9-457b-9a96-776605c7b887
+  spec:
+    schema:
+      AccessControlService:
+        allowable_values:
+        - Enabled
+        - Disabled
+        attribute_type: Enumeration
+        read_only: false
+      # ...
+----

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

@@ -0,0 +1,108 @@
+// Module included in the following assemblies:
+//
+// * edge_computing/ztp-deploying-far-edge-sites.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ztp-retrieving-the-host-firmware-settings_{context}"]
+= Retrieving the host firmware settings for a managed cluster
+
+You can retrieve the host firmware settings for managed clusters.
+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.
+
+.Prerequisites
+
+* You have installed the OpenShift CLI (`oc`).
+
+* You have installed {rh-rhacm-first} and logged in to the hub cluster as a user with `cluster-admin` privileges.
+
+* You have provisioned a cluster that is managed by {rh-rhacm}.
+
+.Procedure
+
+. Retrieve the host firmware settings for the managed cluster.
+Run the following command:
++
+--
+[source,terminal]
+----
+$ oc get hostfirmwaresettings -n <cluster_namespace> <node_name> -o yaml
+----
+
+.Example output
+[source,terminal]
+----
+apiVersion: v1
+items:
+- apiVersion: metal3.io/v1alpha1
+  kind: HostFirmwareSettings
+  metadata:
+    creationTimestamp: "2024-09-11T10:29:43Z"
+    generation: 1
+    name: compute-1.example.com
+    namespace: kni-qe-24
+    ownerReferences:
+    - apiVersion: metal3.io/v1alpha1
+      blockOwnerDeletion: true
+      controller: true
+      kind: BareMetalHost
+      name: compute-1.example.com
+      uid: 0baddbb7-bb34-4224-8427-3d01d91c9287
+    resourceVersion: "280057626"
+    uid: 65d0e89b-1cd8-4317-966d-2fbbbe033fe9
+  spec:
+    settings: {}
+  status:
+    conditions:
+    - lastTransitionTime: "2024-09-11T10:29:43Z"
+      message: ""
+      observedGeneration: 1
+      reason: Success
+      status: "True" <1>
+      type: ChangeDetected
+    - lastTransitionTime: "2024-09-11T10:29:43Z"
+      message: Invalid BIOS setting
+      observedGeneration: 1
+      reason: ConfigurationError
+      status: "False" <2>
+      type: Valid
+    lastUpdated: "2024-09-11T10:29:43Z"
+    schema:
+      name: schema-40562318
+      namespace: compute-1
+    settings: <3>
+      AccessControlService: Enabled
+      AcpiHpet: Enabled
+      AcpiRootBridgePxm: Enabled
+      # ...
+----
+<1> Indicates that a change in the host firmware settings has been detected
+<2> Indicates that the host has an invalid firmware setting
+<3> The complete list of configured host firmware settings is returned under the `status.settings` field
+--
+
+. Optional: Check the status of the `HostFirmwareSettings` (`hfs`) custom resource in the cluster:
++
+[source,terminal]
+----
+$ oc get hfs -n <managed_cluster_namespace> <managed_cluster_name> -o jsonpath='{.status.conditions[?(@.type=="ChangeDetected")].status}'
+----
++
+.Example output
+[source,terminal]
+----
+True
+----
+
+. Optional: Check for invalid firmware settings in the cluster host.
+Run the following command:
++
+[source,terminal]
+----
+$ oc get hfs -n <managed_cluster_namespace> <managed_cluster_name> -o jsonpath='{.status.conditions[?(@.type=="Valid")].status}'
+----
++
+.Example output
+[source,terminal]
+----
+False
+----