Mount host kernel modules in build pods for in-tree dependency resolution

TomerNewman · TomerNewman · commit ee9b60f93e01 · 2026-01-22T15:14:54.000+02:00
Build pods now have access to /host/lib/modules and /host/usr/lib/modules,
allowing depmod to resolve dependencies on in-tree kernel modules during
the build phase. Worker pods updated to use the same paths for consistency.
diff --git a/docs/mkdocs/documentation/kmod_image.md b/docs/mkdocs/documentation/kmod_image.md
@@ -119,16 +119,16 @@ Once the image is built, KMM proceeds with the `Module` reconciliation.
 ### Depending on in-tree kernel modules
 
 Some kernel modules depend on other kernel modules shipped with the node's distribution.
-To avoid copying those dependencies into the kmod image, 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
+To avoid copying those dependencies into the kmod image, KMM mounts the host's `/lib/modules` and `/usr/lib/modules`
+directories into both the build and worker Pod's filesystems at `/host/lib/modules` and `/host/usr/lib/modules`.  
+By creating a symlink from `/opt/lib/modules/[kernel-version]/[symlink-name]` to
+`/host/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 link points to `/usr/lib/modules/[kernel-version]` in the worker Pod, which is mounted from the node's filesystem.
+That link points to `/host/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 example below, we use `host` as the symbolic link name under `/opt/usr/lib/modules/[kernel-version]`:
+In the example below, we use `host` as the symbolic link name under `/opt/lib/modules/[kernel-version]`:
 
 ```dockerfile
 FROM ubuntu as builder
@@ -146,8 +146,8 @@ RUN apt-get update && apt-get 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
+# Create the symbolic link to host modules (mounted at /host/lib/modules by KMM)
+RUN ln -s /host/lib/modules/${KERNEL_FULL_VERSION} /opt/lib/modules/${KERNEL_FULL_VERSION}/host
 
 RUN depmod -b /opt ${KERNEL_FULL_VERSION}
 ```
@@ -156,5 +156,5 @@ RUN depmod -b /opt ${KERNEL_FULL_VERSION}
     `depmod` will generate 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` will expect the files to be present under
-    `/usr/lib/modules/[kernel-version]`, and the same filesystem layout.  
+    `/host/lib/modules/[kernel-version]`, and the same filesystem layout.  
     It is highly recommended that the build and the target nodes share the same distribution and release.
diff --git a/internal/buildsign/resource/common_test.go b/internal/buildsign/resource/common_test.go
@@ -142,6 +142,16 @@ var _ = Describe("makeBuildTemplate", func() {
 								ReadOnly:  true,
 								MountPath: "/workspace",
 							},
+							{
+								Name:      "lib-modules",
+								ReadOnly:  true,
+								MountPath: "/host/lib/modules",
+							},
+							{
+								Name:      "usr-lib-modules",
+								ReadOnly:  true,
+								MountPath: "/host/usr/lib/modules",
+							},
 						},
 					},
 				},
@@ -162,6 +172,24 @@ var _ = Describe("makeBuildTemplate", func() {
 							},
 						},
 					},
+					{
+						Name: "lib-modules",
+						VolumeSource: v1.VolumeSource{
+							HostPath: &v1.HostPathVolumeSource{
+								Path: "/lib/modules",
+								Type: ptr.To(v1.HostPathDirectory),
+							},
+						},
+					},
+					{
+						Name: "usr-lib-modules",
+						VolumeSource: v1.VolumeSource{
+							HostPath: &v1.HostPathVolumeSource{
+								Path: "/usr/lib/modules",
+								Type: ptr.To(v1.HostPathDirectory),
+							},
+						},
+					},
 				},
 			},
 		}
diff --git a/internal/buildsign/resource/volumes.go b/internal/buildsign/resource/volumes.go
@@ -11,6 +11,8 @@ import (
 func makeBuildResourceVolumesAndVolumeMounts(buildConfig kmmv1beta1.Build,
 	imageRepoSecret *v1.LocalObjectReference) ([]v1.Volume, []v1.VolumeMount) {
 
+	hostPathDirectory := v1.HostPathDirectory
+
 	volumes := []v1.Volume{
 		{
 			Name: dockerfileVolumeName,
@@ -26,6 +28,24 @@ func makeBuildResourceVolumesAndVolumeMounts(buildConfig kmmv1beta1.Build,
 				},
 			},
 		},
+		{
+			Name: "lib-modules",
+			VolumeSource: v1.VolumeSource{
+				HostPath: &v1.HostPathVolumeSource{
+					Path: "/lib/modules",
+					Type: &hostPathDirectory,
+				},
+			},
+		},
+		{
+			Name: "usr-lib-modules",
+			VolumeSource: v1.VolumeSource{
+				HostPath: &v1.HostPathVolumeSource{
+					Path: "/usr/lib/modules",
+					Type: &hostPathDirectory,
+				},
+			},
+		},
 	}
 
 	for _, secretRef := range buildConfig.Secrets {
@@ -46,6 +66,16 @@ func makeBuildResourceVolumesAndVolumeMounts(buildConfig kmmv1beta1.Build,
 			ReadOnly:  true,
 			MountPath: "/workspace",
 		},
+		{
+			Name:      "lib-modules",
+			ReadOnly:  true,
+			MountPath: "/host/lib/modules",
+		},
+		{
+			Name:      "usr-lib-modules",
+			ReadOnly:  true,
+			MountPath: "/host/usr/lib/modules",
+		},
 	}
 
 	for _, secretRef := range buildConfig.Secrets {
diff --git a/internal/pod/workerpodmanager.go b/internal/pod/workerpodmanager.go
@@ -388,12 +388,12 @@ func (wpmi *workerPodManagerImpl) baseWorkerPod(ctx context.Context, nmc client.
 		},
 		{
 			Name:      volNameLibModules,
-			MountPath: "/lib/modules",
+			MountPath: "/host/lib/modules",
 			ReadOnly:  true,
 		},
 		{
 			Name:      volNameUsrLibModules,
-			MountPath: "/usr/lib/modules",
+			MountPath: "/host/usr/lib/modules",
 			ReadOnly:  true,
 		},
 		{
diff --git a/internal/pod/workerpodmanager_test.go b/internal/pod/workerpodmanager_test.go
@@ -548,12 +548,12 @@ cp -R /firmware-path/* /tmp/firmware-path;
 						},
 						{
 							Name:      volNameLibModules,
-							MountPath: "/lib/modules",
+							MountPath: "/host/lib/modules",
 							ReadOnly:  true,
 						},
 						{
 							Name:      volNameUsrLibModules,
-							MountPath: "/usr/lib/modules",
+							MountPath: "/host/usr/lib/modules",
 							ReadOnly:  true,
 						},
 						{
diff --git a/internal/worker/worker.go b/internal/worker/worker.go
@@ -49,7 +49,7 @@ func (w *worker) LoadKmod(ctx context.Context, cfg *kmmv1beta1.ModuleConfig, fir
 		w.logger.Info("Unloading in-tree modules", "names", inTreeModulesToRemove)
 		modulesToUnload := make([]string, 0, len(inTreeModulesToRemove))
 		for _, module := range inTreeModulesToRemove {
-			exists, err := w.fh.FileExists("/lib/modules", fmt.Sprintf("^%s.ko", module))
+			exists, err := w.fh.FileExists("/host/lib/modules", fmt.Sprintf("^%s.ko", module))
 			if err != nil {
 				w.logger.Info(utils.WarnString(
 					fmt.Sprintf("failed to check if module file %s present on the host", module)), "error", err)
diff --git a/internal/worker/worker_test.go b/internal/worker/worker_test.go
@@ -82,10 +82,10 @@ var _ = Describe("worker_LoadKmod", func() {
 		}
 
 		gomock.InOrder(
-			fh.EXPECT().FileExists("/lib/modules", "^intree1.ko").Return(true, nil),
-			fh.EXPECT().FileExists("/lib/modules", "^intree2.ko").Return(false, nil),
-			fh.EXPECT().FileExists("/lib/modules", "^intree3.ko").Return(true, nil),
-			fh.EXPECT().FileExists("/lib/modules", "^intree4.ko").Return(false, fmt.Errorf("some error")),
+			fh.EXPECT().FileExists("/host/lib/modules", "^intree1.ko").Return(true, nil),
+			fh.EXPECT().FileExists("/host/lib/modules", "^intree2.ko").Return(false, nil),
+			fh.EXPECT().FileExists("/host/lib/modules", "^intree3.ko").Return(true, nil),
+			fh.EXPECT().FileExists("/host/lib/modules", "^intree4.ko").Return(false, fmt.Errorf("some error")),
 			mr.EXPECT().Run(ctx, "-rv", "intree1", "intree3"),
 			mr.EXPECT().Run(ctx, "-vd", filepath.Join(sharedFilesDir, dirName), moduleName),
 		)
@@ -109,7 +109,7 @@ var _ = Describe("worker_LoadKmod", func() {
 		}
 
 		gomock.InOrder(
-			fh.EXPECT().FileExists("/lib/modules", "^intreeToRemove.ko").Return(true, nil),
+			fh.EXPECT().FileExists("/host/lib/modules", "^intreeToRemove.ko").Return(true, nil),
 			mr.EXPECT().Run(ctx, "-rv", "intreeToRemove"),
 			mr.EXPECT().Run(ctx, "-vd", filepath.Join(sharedFilesDir, dirName), moduleName),
 		)

Original file line number	Diff line number	Diff line change
`@@ -388,12 +388,12 @@ func (wpmi *workerPodManagerImpl) baseWorkerPod(ctx context.Context, nmc client.`
`388`	`388`	`},`
`389`	`389`	`{`
`390`	`390`	`Name: volNameLibModules,`
`391`		`- MountPath: "/lib/modules",`
	`391`	`+ MountPath: "/host/lib/modules",`
`392`	`392`	`ReadOnly: true,`
`393`	`393`	`},`
`394`	`394`	`{`
`395`	`395`	`Name: volNameUsrLibModules,`
`396`		`- MountPath: "/usr/lib/modules",`
	`396`	`+ MountPath: "/host/usr/lib/modules",`
`397`	`397`	`ReadOnly: true,`
`398`	`398`	`},`
`399`	`399`	`{`
Original file line number	Diff line number	Diff line change
`@@ -548,12 +548,12 @@ cp -R /firmware-path/* /tmp/firmware-path;`
`548`	`548`	`},`
`549`	`549`	`{`
`550`	`550`	`Name: volNameLibModules,`
`551`		`- MountPath: "/lib/modules",`
	`551`	`+ MountPath: "/host/lib/modules",`
`552`	`552`	`ReadOnly: true,`
`553`	`553`	`},`
`554`	`554`	`{`
`555`	`555`	`Name: volNameUsrLibModules,`
`556`		`- MountPath: "/usr/lib/modules",`
	`556`	`+ MountPath: "/host/usr/lib/modules",`
`557`	`557`	`ReadOnly: true,`
`558`	`558`	`},`
`559`	`559`	`{`
Original file line number	Diff line number	Diff line change
`@@ -82,10 +82,10 @@ var _ = Describe("worker_LoadKmod", func() {`
`82`	`82`	`}`
`83`	`83`
`84`	`84`	`gomock.InOrder(`
`85`		`- fh.EXPECT().FileExists("/lib/modules", "^intree1.ko").Return(true, nil),`
`86`		`- fh.EXPECT().FileExists("/lib/modules", "^intree2.ko").Return(false, nil),`
`87`		`- fh.EXPECT().FileExists("/lib/modules", "^intree3.ko").Return(true, nil),`
`88`		`- fh.EXPECT().FileExists("/lib/modules", "^intree4.ko").Return(false, fmt.Errorf("some error")),`
	`85`	`+ fh.EXPECT().FileExists("/host/lib/modules", "^intree1.ko").Return(true, nil),`
	`86`	`+ fh.EXPECT().FileExists("/host/lib/modules", "^intree2.ko").Return(false, nil),`
	`87`	`+ fh.EXPECT().FileExists("/host/lib/modules", "^intree3.ko").Return(true, nil),`
	`88`	`+ fh.EXPECT().FileExists("/host/lib/modules", "^intree4.ko").Return(false, fmt.Errorf("some error")),`
`89`	`89`	`mr.EXPECT().Run(ctx, "-rv", "intree1", "intree3"),`
`90`	`90`	`mr.EXPECT().Run(ctx, "-vd", filepath.Join(sharedFilesDir, dirName), moduleName),`
`91`	`91`	`)`
`@@ -109,7 +109,7 @@ var _ = Describe("worker_LoadKmod", func() {`
`109`	`109`	`}`
`110`	`110`
`111`	`111`	`gomock.InOrder(`
`112`		`- fh.EXPECT().FileExists("/lib/modules", "^intreeToRemove.ko").Return(true, nil),`
	`112`	`+ fh.EXPECT().FileExists("/host/lib/modules", "^intreeToRemove.ko").Return(true, nil),`
`113`	`113`	`mr.EXPECT().Run(ctx, "-rv", "intreeToRemove"),`
`114`	`114`	`mr.EXPECT().Run(ctx, "-vd", filepath.Join(sharedFilesDir, dirName), moduleName),`
`115`	`115`	`)`