Merge pull request #63309 from StephenJamesSmith/TELCODOCS-1277

TELCODOCS-1277: first draft

Author: stevsmit

hardware_enablement/kmm-kernel-module-management.adoc

@@ -65,6 +65,9 @@ include::modules/kmm-building-and-signing-a-moduleloader-container-image.adoc[le
 .Additional resources
 For information on creating a service account, see xref:https://docs.openshift.com/container-platform/4.12/authentication/understanding-and-creating-service-accounts.html#service-accounts-managing_understanding-service-accounts[Creating service accounts].
 
+// Added for TELCODOCS-1277
+include::modules/kmm-customizing-upgrades-for-kernel-modules.adoc[leveloffset=+1]
+
 include::modules/kmm-debugging-and-troubleshooting.adoc[leveloffset=+1]
 
 // Added for TELCODOCS-1067

modules/kmm-customizing-upgrades-for-kernel-modules.adoc

@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/kmm-kernel-module-management.adoc
+
+:_content-type: PROCEDURE
+[id="kmm-customizing-upgrades-for-kernel-modules_{context}"]
+= Customizing upgrades for kernel modules
+
+Use this procedure to upgrade the kernel module while running maintenance operations on the node, including rebooting the node, if needed. To minimize the impact on the workloads running in the cluster, run the kernel upgrade process sequentially, one node at a time.
+
+[NOTE]
+====
+This procedure requires knowledge of the workload utilizing the kernel module and must be managed by the cluster administrator.
+====
+
+.Prerequisites
+
+* Before upgrading, set the `kmm.node.kubernetes.io/version-module.<module-namespace>.<module-name>=$moduleVersion` label on all the nodes that will be used by the kernel module.
+
+* Terminate all user application workloads on the node or move them to another node.
+
+* Unload the currently loaded kernel module.
+
+* Ensure that the user workload (the application running in the cluster that is accessing kernel module) is not running on the node prior to kernel module unloading and that the workload is back running on the node after the new kernel module version has been loaded.
+
+* Ensure that the device plugin managed by KMM on the node is unloaded before the upgrade process and reloaded following the upgrade process.
+
+* Due to Kubernetes limitations in label names, the combined length of `Module` name and namespace must not exceed 39 characters.
+
+.Procedure
+
+. Update the following fields in the `Module` CR:
+- `containerImage` (to the appropriate kernel version)
+- `version`
++
+The update should be atomic; that is, both the `containerImage` and `version` fields must be updated simultaneously.
+
+. Terminate any workload using the kernel module on the node being upgraded.
+
+. Remove the `kmm.node.kubernetes.io/version-module.<module-namespace>.<module-name>` label on the node. This unloads the kernel module from the node.
+
+. If required, perform any additional maintenance required on the node for the kernel module upgrade.
+
+. Add the `kmm.node.kubernetes.io/version-module.<module-namespace>.<module-name>=$moduleVersion` label to the node. `$moduleVersion` should be equal to the new value of the `version` field in the `Module` CR.
+
+. Restore any workload that leverages the kernel module on the node.
+
+[NOTE]
+====
+If no additional upgrading is needed, you can skip Steps 3 through 6 by updating the `kmm.node.kubernetes.io/version-module.<module-namespace>.<module-name>` label value to the new `$moduleVersion` as set in the `Module`.
+====