Merge pull request openshift#76414 from openshift-cherrypick-robot/cherry-pick-76114-to-enterprise-4.16

[enterprise-4.16] TELCODOCS-1827: Document symlinks for in-tree dependencies

Author: JoeAldinger

hardware_enablement/kmm-kernel-module-management.adoc

@@ -55,6 +55,10 @@ include::modules/kmm-replacing-in-tree-modules-with-out-of-tree-modules.adoc[lev
 * link:https://fastbitlab.com/building-a-linux-kernel-module/[Building a linux kernel module]
 
 include::modules/kmm-example-module-cr.adoc[leveloffset=+2]
+
+// Added for TELCODOCS-1827
+include::modules/kmm-symbolic-links-for-in-tree-dependencies.adoc[leveloffset=+1]
+
 include::modules/kmm-creating-kmod-image.adoc[leveloffset=+1]
 include::modules/kmm-running-depmod.adoc[leveloffset=+2]
 

modules/kmm-running-depmod.adoc

@@ -20,11 +20,9 @@ You must have a Red Hat subscription to download the `kernel-devel` package.
 +
 [source,terminal]
 ----
-$ depmod -b /opt ${KERNEL_VERSION}+`.
+$ depmod -b /opt ${KERNEL_FULL_VERSION}+`.
 ----
 
-
-
 [id="example-dockerfile_{context}"]
 == Example Dockerfile
 
@@ -42,15 +40,15 @@ data:
   dockerfile: |
     ARG DTK_AUTO
     FROM ${DTK_AUTO} as builder
-    ARG KERNEL_VERSION
+    ARG KERNEL_FULL_VERSION
     WORKDIR /usr/src
     RUN ["git", "clone", "https://github.com/rh-ecosystem-edge/kernel-module-management.git"]
     WORKDIR /usr/src/kernel-module-management/ci/kmm-kmod
-    RUN KERNEL_SRC_DIR=/lib/modules/${KERNEL_VERSION}/build make all
+    RUN KERNEL_SRC_DIR=/lib/modules/${KERNEL_FULL_VERSION}/build make all
     FROM registry.redhat.io/ubi9/ubi-minimal
-    ARG KERNEL_VERSION
+    ARG KERNEL_FULL_VERSION
     RUN microdnf install kmod
-    COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_a.ko /opt/lib/modules/${KERNEL_VERSION}/
-    COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_b.ko /opt/lib/modules/${KERNEL_VERSION}/
-    RUN depmod -b /opt ${KERNEL_VERSION}
+    COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_a.ko /opt/lib/modules/${KERNEL_FULL_VERSION}/
+    COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_b.ko /opt/lib/modules/${KERNEL_FULL_VERSION}/
+    RUN depmod -b /opt ${KERNEL_FULL_VERSION}
 ----

modules/kmm-symbolic-links-for-in-tree-dependencies.adoc

@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/kmm-kernel-module-management.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="kmm-symbolic-links-for-in-tree-dependencies_{context}"]
+
+= Symbolic links for in-tree dependencies
+
+Some kernel modules depend on other kernel modules that are shipped with the node's operating system. To avoid copying those dependencies into the kmod image, Kernel Module Management (KMM) mounts `/usr/lib/modules` into both the build and the worker pod's filesystems.
+
+By creating a symlink from `/opt/usr/lib/modules/<kernel_version>/<symlink_name>` to `/usr/lib/modules/<kernel_version>`, `depmod` can use the in-tree kmods on the building node's filesystem to resolve dependencies.
+
+At runtime, the worker pod extracts the entire image, including the `<symlink_name>` symbolic link. That symbolic link points to `/usr/lib/modules/<kernel_version>` in the worker pod, which is mounted from the node's filesystem. `modprobe` can then follow that link and load the in-tree dependencies as needed.
+
+In the following example, `host` is the symbolic link name under `/opt/usr/lib/modules/<kernel_version>`:
+
+[source,dockerfile]
+----
+ARG DTK_AUTO
+
+FROM ${DTK_AUTO} as builder
+
+#
+# Build steps
+#
+
+FROM ubi9/ubi
+
+ARG KERNEL_FULL_VERSION
+
+RUN dnf update && dnf install -y kmod
+
+COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_a.ko /opt/lib/modules/${KERNEL_FULL_VERSION}/
+COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_b.ko /opt/lib/modules/${KERNEL_FULL_VERSION}/
+
+# Create the symbolic link
+RUN ln -s /lib/modules/${KERNEL_FULL_VERSION} /opt/lib/modules/${KERNEL_FULL_VERSION}/host
+
+RUN depmod -b /opt ${KERNEL_FULL_VERSION}
+----
+
+[NOTE]
+====
+`depmod` generates dependency files based on the kernel modules present on the node that runs the kmod image build.
+
+On the node on which KMM loads the kernel modules, `modprobe` expects the files to be present under `/usr/lib/modules/<kernel_version>`, and the same filesystem layout. It is highly recommended that the build and the target nodes share the same operating system and release.
+====

modules/kmm-using-driver-toolkit.adoc

@@ -25,15 +25,15 @@ The value is automatically set by KMM when creating the `Build` resource. See th
 ----
 ARG DTK_AUTO
 FROM ${DTK_AUTO} as builder
-ARG KERNEL_VERSION
+ARG KERNEL_FULL_VERSION
 WORKDIR /usr/src
 RUN ["git", "clone", "https://github.com/rh-ecosystem-edge/kernel-module-management.git"]
 WORKDIR /usr/src/kernel-module-management/ci/kmm-kmod
-RUN KERNEL_SRC_DIR=/lib/modules/${KERNEL_VERSION}/build make all
-FROM registry.redhat.io/ubi9/ubi-minimal
-ARG KERNEL_VERSION
+RUN KERNEL_SRC_DIR=/lib/modules/${KERNEL_FULL_VERSION}/build make all
+FROM ubi9/ubi-minimal
+ARG KERNEL_FULL_VERSION
 RUN microdnf install kmod
-COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_a.ko /opt/lib/modules/${KERNEL_VERSION}/
-COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_b.ko /opt/lib/modules/${KERNEL_VERSION}/
-RUN depmod -b /opt ${KERNEL_VERSION}
+COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_a.ko /opt/lib/modules/${KERNEL_FULL_VERSION}/
+COPY --from=builder /usr/src/kernel-module-management/ci/kmm-kmod/kmm_ci_b.ko /opt/lib/modules/${KERNEL_FULL_VERSION}/
+RUN depmod -b /opt ${KERNEL_FULL_VERSION}
 ----