Repository navigation
Add PRD for modprobe.d config file support #1874
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,169 @@ | ||
| # Modprobe.d Configuration Files for Driver Container Images | ||
|
|
||
| | Field | Value | | ||
| |-------------|---------| | ||
| | Author(s) | Natali Shemtov | | ||
| | Date | 2026-07-29 | | ||
|
|
||
| ## 1. Problem Statement | ||
|
|
||
| Kernel modules can subscribe to multiple kernel subsystems during | ||
| initialization (for example, PCI). Each subscription increments the | ||
| module's reference count. When the module needs to be unloaded, its exit | ||
| function isn't called until that reference count reaches zero — which | ||
| typically requires running a user-space script to unwind those | ||
| subscriptions first. Today, KMM users have no way to run such a script | ||
| before or after `modprobe` loads or unloads their kernel module, so | ||
| modules that rely on this pattern cannot be reliably unloaded through KMM. | ||
|
|
||
| ## 2. Goals and Non-Goals | ||
|
|
||
| ### 2.1 Goals | ||
|
|
||
| - Users can supply a set of modprobe.d configuration files in their driver | ||
| container image, and have KMM apply them so that the corresponding | ||
| init/de-init scripts run automatically when the kernel module is loaded | ||
| and unloaded. | ||
| - The modprobe.d capability works correctly together with the existing | ||
| Firmware loading capability, with no degradation to either. | ||
| - Users are always informed when their modprobe.d configuration could not | ||
| be applied, rather than experiencing a silent failure. | ||
| - The modprobe.d capability introduces no degradation to the existing | ||
| `ModulesLoadingOrder` capability — achieved by preventing the two from | ||
| being enabled together on the same module (see Non-Goals), rather than | ||
| allowing them to silently conflict. | ||
| - Users can specify where in their driver container image their | ||
| modprobe.d files live, via a new field on the Module API. KMM always | ||
| copies those files to the same fixed location on the worker pod | ||
| (`/etc/modprobe.d/`), regardless of the configured source path. | ||
| Modules that don't set the field are unaffected (see NFR-2). | ||
|
|
||
| ### 2.2 Non-Goals | ||
|
|
||
| - Live reconfiguration: applying a new or changed set of modprobe.d files | ||
| to an already-running module requires the user to restart/recreate the | ||
| module's worker pods. | ||
| - Validation of modprobe.d file contents: KMM does not check or validate | ||
| the syntax of the modprobe.d files a user provides — malformed files | ||
| fail at `modprobe` execution time, not as a KMM-reported error. | ||
| - Nested directory structures: only modprobe.d files placed directly in | ||
| the configured directory are supported. Files placed in sub-directories | ||
| are not picked up. | ||
| - Combined use with `ModulesLoadingOrder`: `ModulesLoadingOrder` is | ||
| implemented today by mounting a read-only volume at `/etc/modprobe.d/` | ||
| in the worker Pod, which collides with this capability's use of the | ||
| same path. Merging both into a single input (for example, generating | ||
| and mounting the combined configuration from an init container) is a | ||
| long-term solution that is out of scope for this enhancement. Users who | ||
| need both softdep-style module ordering and other modprobe.d directives | ||
| can express the ordering directly in their own modprobe.d files. | ||
|
|
||
| ## 3. Requirements | ||
|
|
||
| ### 3.1 Functional Requirements | ||
|
|
||
| - **FR-1:** Users must be able to enable the modprobe.d capability on a | ||
| module by setting a new field on the Module API that specifies the | ||
| directory in their driver container image containing their modprobe.d | ||
| configuration files. The field accepts any well-formed absolute path; | ||
| KMM's validating webhook must reject the Module if the value isn't a | ||
| well-formed absolute path, but otherwise does not restrict which | ||
| directory the user chooses. | ||
| - **FR-2:** When a module has the modprobe.d capability enabled, the | ||
| configuration files in `/etc/modprobe.d/` must take effect before | ||
| `modprobe` is invoked to load the kernel module, so that any load-time | ||
| init sequence defined in those files runs automatically. | ||
| - **FR-3:** When a module has the modprobe.d capability enabled, the | ||
| configuration files in `/etc/modprobe.d/` must take effect before | ||
| `modprobe` is invoked to unload the kernel module, so that any de-init | ||
| sequence defined in those files runs automatically (including | ||
| sequences needed to release kernel subsystem reference counts before | ||
|
Comment on lines
+72
to
+80
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
sed -n '55,95p' docs/enhancements/0005-modprobed-config.mdRepository: rh-ecosystem-edge/kernel-module-management Length of output: 2581 🌐 Web query:
💡 Result: The install and remove directives in modprobe.d(5) are configuration commands used to override the default kernel module insertion and removal behavior [1][2]. Install directive: The install modulename command instructs modprobe to execute a specified shell command instead of directly inserting the module into the kernel [1][2]. This is typically used for complex tasks, such as loading other required modules before the target module [1]. Remove directive: The remove modulename command functions similarly to the install command but is triggered when modprobe -r is executed [1][2]. --ignore-install and --ignore-remove behavior: The --ignore-install and --ignore-remove options (or -i) are used with the modprobe command to prevent it from executing these custom install and remove commands defined in the configuration files [3][4]. When either --ignore-install or --ignore-remove is used, modprobe ignores both types of commands for the module specified on the command line [3][4]. Dependent modules, however, remain subject to any install or remove commands defined for them in the configuration [3][4]. A common use case for these options is within the install command itself to avoid infinite loops [1][2]. For example, if you define an install command to load "barney" before "fred", you might use /sbin/modprobe --ignore-install fred to ensure the second modprobe call triggers the default insertion rather than re-triggering the custom install command [1][2]. Citations:
🏁 Script executed: #!/bin/bash
python3 - <<'PY'
from urllib.request import urlopen
url = "https://man7.org/linux/man-pages/man5/modprobe.d.5.html"
text = urlopen(url, timeout=10).read().decode("utf-8", "replace").lower()
checks = {
"install replaces normal insertion": "instead of inserting the module normally" in text,
"remove replaces normal removal": "instead of removing the module normally" in text,
"ignore-install exists": "--ignore-install" in text,
"ignore-remove exists": "--ignore-remove" in text,
"ignore options used to avoid recursion": "infinite loop" in text,
}
for name, result in checks.items():
print(f"{name}: {result}")
PY
rg -n -i 'install|remove|ignore-install|ignore-remove|pre-hook|hook' \
docs/enhancements/0005-modprobed-config.mdRepository: rh-ecosystem-edge/kernel-module-management Length of output: 2903 🏁 Script executed: #!/bin/bash
set -e
python3 - <<'PY'
import re
import ssl
from urllib.request import urlopen
url = "https://man7.org/linux/man-pages/man5/modprobe.d.5.html"
context = ssl._create_unverified_context()
html = urlopen(url, context=context, timeout=10).read().decode("utf-8", "replace")
text = re.sub(r"<[^>]+>", " ", html)
text = re.sub(r"\s+", " ", text).lower()
for term in (
"instead of inserting the module normally",
"instead of removing the module normally",
"--ignore-install",
"--ignore-remove",
):
print(f"{term}: {term in text}")
PY
sed -n '1,180p' docs/enhancements/0005-modprobed-config.mdRepository: rh-ecosystem-edge/kernel-module-management Length of output: 9392 Define 🤖 Prompt for AI Agents |
||
| unload can proceed). | ||
| - **FR-4:** If the directory configured for the modprobe.d capability | ||
| does not exist in the driver container image, or exists but contains no | ||
| files, the module must fail to load rather than silently proceeding | ||
| without the modprobe.d configuration. | ||
|
NataliShemtov marked this conversation as resolved.
|
||
| - **FR-5:** If the directory configured for the modprobe.d capability | ||
| contains a sub-directory, the module must fail to load. | ||
| - **FR-6:** Applying an updated set of modprobe.d files requires the user | ||
| to restart or recreate the module's worker pods; a running pod does not | ||
| pick up changes to the configured directory automatically. | ||
| - **FR-7:** The modprobe.d capability must continue to work correctly for | ||
| modules that also use Firmware loading. | ||
| - **FR-8:** KMM must reject, via validating webhook, any Module that | ||
| enables the modprobe.d capability while also setting | ||
| `ModulesLoadingOrder`, since the two currently cannot coexist (see | ||
| Non-Goals). The rejection must clearly state why the combination isn't | ||
| supported and point the user to expressing module ordering directly in | ||
| their own modprobe.d files instead. | ||
|
|
||
| ### 3.2 Non-Functional Requirements | ||
|
|
||
| - **NFR-1:** Enabling the modprobe.d capability on a module requires that | ||
| module's worker pods to run with a Privileged security context, applied | ||
| automatically by KMM. Users must be able to determine, before deploying, | ||
| that enabling the modprobe.d capability implies this elevated privilege | ||
| level for the module's worker pods. | ||
|
NataliShemtov marked this conversation as resolved.
|
||
| - **NFR-2:** Modules that do not enable the modprobe.d capability continue | ||
| to behave exactly as they do today — this capability introduces no | ||
| change for existing modules. | ||
| - **NFR-3:** When the modprobe.d configuration cannot be applied (per | ||
| FR-4 or FR-5), the user must be able to observe the failure and its | ||
| cause through the Module's status or an Openshift event, without having | ||
| to inspect pod logs to discover it. | ||
|
NataliShemtov marked this conversation as resolved.
|
||
|
|
||
| ## 4. Acceptance Criteria | ||
|
|
||
| - [ ] A user can enable the modprobe.d capability on a module and place | ||
| configuration files in the directory they configured in their | ||
| driver container image, and after deploying the Module, the | ||
| load-time init sequence defined in those files runs as part of | ||
| loading the kernel module. | ||
| - [ ] The de-init sequence defined in the user's modprobe.d files runs as | ||
| part of unloading the kernel module, including for modules that | ||
| require this sequence to release subsystem reference counts before | ||
| `modprobe -r` can succeed. | ||
| - [ ] A user who enables the modprobe.d capability but whose image has no | ||
| directory at the configured path, or an empty one, sees the module | ||
| fail to load and can observe the failure via the Module's status or | ||
| an Openshift event. | ||
| - [ ] A user who enables the modprobe.d capability and whose configured | ||
| directory contains a sub-directory sees the module fail to load and | ||
| can observe the failure via the Module's status or an Openshift | ||
| event. | ||
| - [ ] A user can use the modprobe.d capability on a module that also uses | ||
| Firmware loading, and both capabilities work correctly together. | ||
| - [ ] A user who tries to enable the modprobe.d capability on a module | ||
| that also sets `ModulesLoadingOrder` is rejected by the validating | ||
| webhook, with a message explaining the conflict and the | ||
| recommended workaround. | ||
| - [ ] A user who sets the modprobe.d field to a value that isn't a | ||
| well-formed absolute path is rejected by the validating webhook. | ||
|
|
||
| ## 5. Assumptions | ||
|
|
||
| - Clusters that adopt this feature permit Privileged pods for modules | ||
| that use it — clusters that uniformly block Privileged pods (e.g., via | ||
| a "restricted" PodSecurity standard applied without exception) would be | ||
| unable to use this capability at all. This mirrors an existing | ||
| precondition for modules that use Firmware loading today, which is | ||
| already documented. | ||
| - Users authoring modprobe.d configuration files are already familiar with | ||
| the modprobe.d file format; KMM provides no authoring assistance or | ||
| content validation. | ||
|
|
||
| ## 6. Future Work | ||
|
|
||
| - **Long-term merge:** revisit combining KMM-generated configuration | ||
| (for example, the softdep config produced for `ModulesLoadingOrder`) | ||
| and user-supplied modprobe.d files into a single input, so the two | ||
| capabilities can be used together. This likely requires moving away | ||
| from the current read-only DownwardAPI-based mount for | ||
| `ModulesLoadingOrder` toward generating configuration into a shared, | ||
| writable volume (for example, from an init container). | ||
| - **Remove `ModulesLoadingOrder`:** once the modprobe.d capability is | ||
| available, users can express module load ordering directly in their | ||
| own modprobe.d files, making the `ModulesLoadingOrder` field redundant. | ||
| Track a follow-up task to remove it from the API in KMM 3.0 (the next | ||
| version where breaking API changes for existing users are permitted), | ||
| once this enhancement's work is complete. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Make failure reporting cover every configuration application failure.
The goal requires users to be informed whenever configuration cannot be applied. NFR-3 covers only missing, empty, or nested directories. The proposal does not define status or event reporting for copy failures, permission errors, destination failures, or modprobe errors. The non-goal also allows malformed files to fail during modprobe without a KMM-reported error. Add requirements and acceptance tests for these failure paths, or narrow the goal.
Also applies to: 46-48, 110-113
🤖 Prompt for AI Agents