TELCODOCS-2595: KMM operator to support upgrades on the Day1 MachineConfig

hardware_enablement/kmm-kernel-module-management.adoc

@@ -192,6 +192,9 @@ include::modules/kmm-day1-machineconfigpool.adoc[leveloffset=+2]
 .Additional resources
 * link:https://www.redhat.com/en/blog/openshift-container-platform-4-how-does-machine-config-pool-work[About MachineConfigPool]
 
+// Added TELCODOCS-2595
+include::modules/kmm-managing-day1-kmod-images.adoc[leveloffset=+1]
+
 include::modules/kmm-debugging-and-troubleshooting.adoc[leveloffset=+1]
 
 // Added for TELCODOCS-1067

modules/kmm-managing-day1-kmod-images.adoc

@@ -0,0 +1,52 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/kmm-kernel-module-management.adoc
+:_mod-docs-content-type: CONCEPT
+[id="kmm-managing-day1-kmod-images_{context}"]
+= Managing Day 1 kmod images
+
+[role="_abstract"]
+Kmod images using the Day 1 utility can be managed by the KMM Operator for full lifecycle management.
+
+In cases where a kmod was installed using the Day 1 utility and a `MachineConfig` is present in the cluster you can create a `Module` in the cluster targetting the same kmod and kernel as the `MachineConfig`. The KMM Operator attempts to load the kmod, but nothing will happen since it is already loaded in the kernel. Future upgrades can be done like Day 2 operations by updating the `Module` CR in the cluster.
+
+The problem with this approach is if a sudden node reboot occurs, the node is rebooted with the kmod from the `MachineConfig` and not the kmod from the `Module` if a kmod upgrade was performed.
+
+Using a `BootMachineConfig` (BMC) CRD can mitigate this issue. When a Day 1 kmod is transitioned to the KMM Operator using a `Module`, a BMC needs to be created in the cluster to address the sudden reboot issues by ensuring that the `MachineConfig` is updated with the correct values without triggering a node reboot.
+
+The following example shows a typical `BootMachineConfig` CRD:
+
+[source,yaml]
+----
+apiVersion: kmm.sigs.x-k8s.io/v1beta1
+ kind: BootModuleConfig
+ metadata:
+  name: example-bmc
+  namespace: openshift-machine-config-operator
+ spec:
+  machineConfigName: worker-kmod-config
+  machineConfigPoolName: worker
+  kernelModuleImage: quay.io/example/kmod
+  kernelModuleName: my_module
+  inTreeModulesToRemove:
+    - intree_module_1
+    - intree_module_2
+  firmwareFilesPath: /firmware
+  workerImage: quay.io/<USER>/kernel-module-management-worker:latest  
+ status:
+  conditions: []
+----
+
+`machineConfigName`:: The `machineConfig` that is targeted by the BMC.
+
+`machineConfigPoolName`:: The `machineConfig` pool that is linked to the targeted `machineConfig`.
+
+`kernelModuleImage`:: The kernel module container image that contains the kernel module `.ko` file without the tag. The pull service determines the kernel version of the node and then uses this value as a tag for the kernel module image. Before upgrading the cluster, all you need to do is to create a kernel module image with the appropriate tag, without any need to update the Day 1 `machineConfig`. When the node is rebooted, the pull service pulls the correct image.
+
+`kernelModuleName`:: The name of the kernel module to be loaded (the name of the `.ko` file without the `.ko`).
+
+`inTreeModulesToRemove`:: An optional list of the in-tree kernel module to remove prior to loading the OOT kernel module.
+
+`firmwareFilesPath`:: An optional path of the firmware files in the kernel module container image.
+
+`workerImage`:: An optional KMM worker image. If not specified, the current worker image is used.