// Module included in the following assemblies:
//
// * hardware_enablement/kmm-kernel-module-management.adoc

:_mod-docs-content-type: PROCEDURE
[id="kmm-customizing-upgrades-for-kernel-modules_{context}"]
= Customizing upgrades for kernel modules

[role="_abstract"]
The Kernel Module Management (KMM) Operator periodically upgrades `Module` resources in the cluster, typically during a cluster upgrade.  

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 using 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 are used by the kernel module.

* End 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 before the kernel module unloads and that the workload is back running on the node after the new kernel module version has been loaded.

.Procedure

. Ensure that the device plugin managed by KMM on the node is unloaded.

. Update the following fields in the `Module` custom resource (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.

. End 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.
Run the following command to unload the kernel module from the node:
+
[source,terminal]
----
$ oc label node/<node_name> kmm.node.kubernetes.io/version-module.<module_namespace>.<module_name>-
----

. If required, as the cluster administrator, perform any additional maintenance required on the node for the kernel module upgrade.
+
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`.

. Run the following command to add the `kmm.node.kubernetes.io/version-module.<module_namespace>.<module_name>=$moduleVersion` label to the node. The `$moduleVersion` must be equal to the new value of the `version` field in the `Module` CR.
+
[source,terminal]
----
$ oc label node/<node_name> kmm.node.kubernetes.io/version-module.<module_namespace>.<module_name>=<desired_version>
----
+
[NOTE]
====
Because of Kubernetes limitations in label names, the combined length of `Module` name and namespace must not exceed 39 characters.
====
+ 
The Operator labels the node with a `version.ready` label to indicate that the new version of the kernel module is loaded and is ready to be used:
+
.Example output
[source,terminal]
----
`kmm.node.kubernetes.io/<module-namespace>.<module-name>.version.ready=<module-version>`
----

. Restore any workload that leverages the kernel module on the node.

. Reload the device plugin managed by KMM on the node.
