diff --git a/edge_computing/ztp-deploying-far-edge-sites.adoc b/edge_computing/ztp-deploying-far-edge-sites.adoc index 3feb189e2e5f..675e09edee51 100644 --- a/edge_computing/ztp-deploying-far-edge-sites.adoc +++ b/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] diff --git a/modules/ztp-configuring-host-firmware-with-gitops-ztp.adoc b/modules/ztp-configuring-host-firmware-with-gitops-ztp.adoc new file mode 100644 index 000000000000..78646ad507b3 --- /dev/null +++ b/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. diff --git a/modules/ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp.adoc b/modules/ztp-deploying-user-defined-firmware-configuration-with-gitops-ztp.adoc new file mode 100644 index 000000000000..8f557ce3f367 --- /dev/null +++ b/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 -o jsonpath='{.status.conditions[?(@.type=="Valid")].status}' +---- ++ +.Example output +[source,terminal] +---- +True +---- diff --git a/modules/ztp-retrieving-the-host-firmware-schema.adoc b/modules/ztp-retrieving-the-host-firmware-schema.adoc new file mode 100644 index 000000000000..c4ae6c971241 --- /dev/null +++ b/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 -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 + # ... +---- diff --git a/modules/ztp-retrieving-the-host-firmware-settings.adoc b/modules/ztp-retrieving-the-host-firmware-settings.adoc new file mode 100644 index 000000000000..c4c112fa7162 --- /dev/null +++ b/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 -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 -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 -o jsonpath='{.status.conditions[?(@.type=="Valid")].status}' +---- ++ +.Example output +[source,terminal] +---- +False +----