From 0b4303bd8bd13b09e810a31ee59d3d1cea5b6bd9 Mon Sep 17 00:00:00 2001 From: StephenJamesSmith Date: Thu, 9 May 2024 17:46:50 -0400 Subject: [PATCH] TELCODOCS-1826: First draft --- .../kmm-kernel-module-management.adoc | 5 +++ modules/kmm-day0-day2-installation.adoc | 28 +++++++++++++++ .../kmm-day0-day2-lifecycle-management.adoc | 36 +++++++++++++++++++ modules/kmm-layering-background.adoc | 11 ++++++ 4 files changed, 80 insertions(+) create mode 100644 modules/kmm-day0-day2-installation.adoc create mode 100644 modules/kmm-day0-day2-lifecycle-management.adoc create mode 100644 modules/kmm-layering-background.adoc diff --git a/hardware_enablement/kmm-kernel-module-management.adoc b/hardware_enablement/kmm-kernel-module-management.adoc index aefa88a618..77935a9c44 100644 --- a/hardware_enablement/kmm-kernel-module-management.adoc +++ b/hardware_enablement/kmm-kernel-module-management.adoc @@ -159,6 +159,11 @@ include::modules/kmm-configuring-the-lookup-path-on-nodes.adoc[leveloffset=+2] include::modules/kmm-building-a-kmod-image.adoc[leveloffset=+2] include::modules/kmm-tuning-the-module-resource.adoc[leveloffset=+2] +// Added for TELCODOCS-1826 +include::modules/kmm-day0-day2-installation.adoc[leveloffset=+1] +include::modules/kmm-layering-background.adoc[leveloffset=+2] +include::modules/kmm-day0-day2-lifecycle-management.adoc[leveloffset=+2] + // Added for TELCODOCS-1059 include::modules/kmm-troubleshooting.adoc[leveloffset=+1] // Added for TELCODOCS-1820 diff --git a/modules/kmm-day0-day2-installation.adoc b/modules/kmm-day0-day2-installation.adoc new file mode 100644 index 0000000000..533a8f66a0 --- /dev/null +++ b/modules/kmm-day0-day2-installation.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * updating/preparing_for_updates/kmm-preflight-validation.adoc + +:_mod-docs-content-type: CONCEPT +[id="kmm-day0-day2-installation_{context}"] += Day 0 through Day 2 kmod installation + +You can install some kernel modules (kmods) during Day 0 through Day 2 operations without Kernel Module Management (KMM). This could assist in the transition of the kmods to KMM. + +Use the following criteria to determine suitable kmod installations. + +Day 0:: The most basic kmods that are required for a node to become `Ready` in the cluster. Examples of these types of kmods include: ++ +* A storage driver that is required to mount the rootFS as part of the boot process +* A network driver that is required for the machine to access `machine-config-server` on the bootstrap node to pull the ignition and join the cluster + +Day 1:: Kmods that are not required for a node to become `Ready` in the cluster but cannot be unloaded when the node is `Ready`. ++ +An example of this type of kmod is an out-of-tree (OOT) network driver that replaces an outdated in-tree driver to exploit the full potential of the NIC while `NetworkManager` depends on it. When the node is `Ready`, you cannot unload the driver because of the `NetworkManager` dependency. + +Day 2:: Kmods that can be dynamically loaded to the kernel or removed from it without interfering with the cluster infrastructure, for example, connectivity. ++ +Examples of these types of kmods include: ++ +* GPU operators +* Secondary network adapters +* field-programmable gate arrays (FPGAs) diff --git a/modules/kmm-day0-day2-lifecycle-management.adoc b/modules/kmm-day0-day2-lifecycle-management.adoc new file mode 100644 index 0000000000..685805fddd --- /dev/null +++ b/modules/kmm-day0-day2-lifecycle-management.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * updating/preparing_for_updates/kmm-preflight-validation.adoc + +:_mod-docs-content-type: CONCEPT +[id="kmm-day0-day2-lifecycle-management_{context}"] += Lifecycle management + +You can leverage KMM to manage the Day 0 through Day 2 lifecycle of kmods without a reboot when the driver allows it. + +[NOTE] +==== +This will not work if the upgrade requires a node reboot, for example, when rebuilding `initramfs` files is needed. +==== + +Use one of the following options for lifecycle management. + +[id="kmm-kmod-in-tree-driver_{context}"] +== Treat the kmod as an in-tree driver + +Use this method when you want to upgrade the kmods. In this case, treat the kmod as an in-tree driver and create a `Module` in the cluster with the `inTreeRemoval` field to unload the old version of the driver. + +Note the following characteristics of treating the kmod as an in-tree driver: + +* Downtime might occur as KMM tries to unload and load the kmod on all the selected nodes simultaneously. +* This works if removing the driver makes the node lose connectivity because KMM uses a single pod to unload and load the driver. + +[id="kmm-ordered-upgrade_{context}"] +== Use ordered upgrade + +You can use ordered upgrade (ordered_upgrade.md) to create a versioned `Module` in the cluster representing the kmods with no effect, because the kmods are already loaded. + +Note the following characteristics of using ordered upgrade: + +* There is no cluster downtime because you control the pace of the upgrade and how many nodes are upgraded at the same time; therefore, an upgrade with no downtime is possible. +* This method will not work if unloading the driver results in losing connection to the node, because KMM creates two different worker pods for unloading and another for loading. These pods will not be scheduled. diff --git a/modules/kmm-layering-background.adoc b/modules/kmm-layering-background.adoc new file mode 100644 index 0000000000..80ca440341 --- /dev/null +++ b/modules/kmm-layering-background.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * updating/preparing_for_updates/kmm-preflight-validation.adoc + +:_mod-docs-content-type: CONCEPT +[id="kmm-layering-background_{context}"] += Layering background + +When a Day 0 kmod is installed in the cluster, layering is applied through the Machine Config Operator (MCO) and {product-title} upgrades do not trigger node upgrades. + +You only need to recompile the driver if you add new features to it, because the node’s operating system will remain the same.