From f36b10d282f809acc8575473cbf057567c772a35 Mon Sep 17 00:00:00 2001 From: Jaromir Hradilek Date: Fri, 11 Jul 2025 17:28:39 +0200 Subject: [PATCH] Updated KMM Operator modules to pass DITA validation. --- ...ing-tolerations-to-kernel-module-pods.adoc | 36 ++++++++++--------- ...kmm-building-and-signing-a-kmod-image.adoc | 3 -- ...igning-a-moduleloader-container-image.adoc | 3 -- modules/kmm-configuring-kmmo.adoc | 8 ++--- modules/kmm-gathering-data-for-kmm-hub.adoc | 5 ++- modules/kmm-gathering-data-for-kmm.adoc | 5 ++- ...installing-kmm-hub-creating-resources.adoc | 2 +- modules/kmm-hub-running-kmm-on-the-spoke.adoc | 4 +-- modules/kmm-installing-older-versions.adoc | 3 +- modules/kmm-installing-using-cli.adoc | 3 +- modules/kmm-observing-events.adoc | 2 -- modules/kmm-reading-operator-logs.adoc | 16 ++++----- modules/kmm-running-depmod.adoc | 7 ++-- ...m-signing-a-prebuilt-driver-container.adoc | 1 - ...kmm-signing-kmods-in-a-prebuilt-image.adoc | 1 - ...kmm-uninstalling-kmmo-red-hat-catalog.adoc | 4 +-- modules/kmm-using-driver-toolkit.adoc | 4 +-- modules/kmm-using-intree-modules.adoc | 4 ++- modules/kmm-using-signing-with-kmm.adoc | 3 +- modules/kmm-validation-status.adoc | 6 ++-- 20 files changed, 58 insertions(+), 62 deletions(-) diff --git a/modules/kmm-applying-tolerations-to-kernel-module-pods.adoc b/modules/kmm-applying-tolerations-to-kernel-module-pods.adoc index 02530a82fbc5..40e927468bba 100644 --- a/modules/kmm-applying-tolerations-to-kernel-module-pods.adoc +++ b/modules/kmm-applying-tolerations-to-kernel-module-pods.adoc @@ -18,7 +18,24 @@ Taints and tolerations consist of `effect`, `key`, and `value` parameters. Toler `tolerationSeconds`:: Represents the period of time the toleration (which must be of effect `NoExecute`, otherwise this field is ignored) tolerates the taint. By default, it is not set and the taint is tolerated forever without eviction. Zero and negative values are treated as `0` and immediately evicted by the system. +Toleration values must match the taint that is added to the nodes. A toleration matches a taint: + +* If the `operator` parameter is set to `Equal`: + +** the `key` parameters are the same; + +** the `value` parameters are the same; + +** the `effect` parameters are the same. + +* If the `operator` parameter is set to `Exists`: + +** the `key` parameters are the same; + +** the `effect` parameters are the same. + .Example taint in a node specification +==== [source,yaml] ---- apiVersion: v1 @@ -33,8 +50,10 @@ spec: value: value1 #... ---- +==== .Example toleration in a module specification +==== [source,yaml] ---- apiVersion: kmm.sigs.x-k8s.io/v1beta1 @@ -50,19 +69,4 @@ spec: tolerationSeconds: 36000 value: value1 ---- - -Toleration values must match the taint that is added to the nodes. A toleration matches a taint: - -* If the `operator` parameter is set to `Equal`: - -** the `key` parameters are the same; - -** the `value` parameters are the same; - -** the `effect` parameters are the same. - -* If the `operator` parameter is set to `Exists`: - -** the `key` parameters are the same; - -** the `effect` parameters are the same. \ No newline at end of file +==== diff --git a/modules/kmm-building-and-signing-a-kmod-image.adoc b/modules/kmm-building-and-signing-a-kmod-image.adoc index e077a2cc6ec8..6d54727ff05f 100644 --- a/modules/kmm-building-and-signing-a-kmod-image.adoc +++ b/modules/kmm-building-and-signing-a-kmod-image.adoc @@ -77,9 +77,6 @@ spec: selector: # top-level selector kubernetes.io/arch: amd64 ---- - <1> Replace `default` with a valid namespace. - <2> The default `serviceAccountName` does not have the required permissions to run a module that is privileged. For information on creating a service account, see "Creating service accounts" in the "Additional resources" of this section. - <3> Used as `imagePullSecrets` in the `DaemonSet` object and to pull and push for the build and sign features. diff --git a/modules/kmm-building-and-signing-a-moduleloader-container-image.adoc b/modules/kmm-building-and-signing-a-moduleloader-container-image.adoc index 7da6d9666d21..9daf6736e5ac 100644 --- a/modules/kmm-building-and-signing-a-moduleloader-container-image.adoc +++ b/modules/kmm-building-and-signing-a-moduleloader-container-image.adoc @@ -77,9 +77,6 @@ spec: selector: # top-level selector kubernetes.io/arch: amd64 ---- - <1> `namespace` - Replace `default` with a valid namespace. - <2> `serviceAccountName` - The default `serviceAccountName` does not have the required permissions to run a module that is privileged. For information on creating a service account, see "Creating service accounts" in the "Additional resources" of this section. - <3> `imageRepoSecret` - Used as `imagePullSecrets` in the `DaemonSet` object and to pull and push for the build and sign features. diff --git a/modules/kmm-configuring-kmmo.adoc b/modules/kmm-configuring-kmmo.adoc index f23089d13c09..38e8068df228 100644 --- a/modules/kmm-configuring-kmmo.adoc +++ b/modules/kmm-configuring-kmmo.adoc @@ -17,9 +17,7 @@ In most cases, the default configuration for the Kernel Module Management (KMM) $ oc rollout restart -n "$namespace" deployment/kmm-operator-controller ---- + -The value of `$namespace` depends on your installation method. -+ -.Example output +The value of `$namespace` depends on your installation method. For example: + [source,yaml] ---- @@ -33,12 +31,12 @@ metadata: name: kmm-operator-manager-config namespace: openshift-kmm ---- - ++ [NOTE] ==== If you want to configure `KMM Hub`, create the `ConfigMap` using the name `kmm-operator-hub-manager-config` in the KMM Hub controller's namespace. ==== - ++ .Operator configuration parameters [cols="2,8",options="header"] |=== diff --git a/modules/kmm-gathering-data-for-kmm-hub.adoc b/modules/kmm-gathering-data-for-kmm-hub.adoc index d02f21c4ae00..b812de51b9a5 100644 --- a/modules/kmm-gathering-data-for-kmm-hub.adoc +++ b/modules/kmm-gathering-data-for-kmm-hub.adoc @@ -37,9 +37,9 @@ $ oc adm must-gather --image="${MUST_GATHER_IMAGE}" -- /usr/bin/gather -u $ oc logs -fn openshift-kmm-hub deployments/kmm-operator-hub-controller ---- + -.Example output +Example output: ++ [%collapsible] -==== [source,terminal] ---- I0417 11:34:08.807472 1 request.go:682] Waited for 1.023403273s due to client-side throttling, not priority and fairness, request: GET:https://172.30.0.1:443/apis/tuned.openshift.io/v1?timeout=32s @@ -68,4 +68,3 @@ I0417 11:34:12.501947 1 controller.go:227] kmm-hub "msg"="Starting workers I0417 11:34:12.501948 1 controller.go:227] kmm-hub "msg"="Starting workers" "controller"="ManagedClusterModule" "controllerGroup"="hub.kmm.sigs.x-k8s.io" "controllerKind"="ManagedClusterModule" "worker count"=1 I0417 11:34:12.502285 1 imagestream_reconciler.go:50] kmm-hub "msg"="registered imagestream info mapping" "ImageStream"={"name":"driver-toolkit","namespace":"openshift"} "controller"="imagestream" "controllerGroup"="image.openshift.io" "controllerKind"="ImageStream" "dtkImage"="quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:df42b4785a7a662b30da53bdb0d206120cf4d24b45674227b16051ba4b7c3934" "name"="driver-toolkit" "namespace"="openshift" "osImageVersion"="412.86.202302211547-0" "reconcileID"="e709ff0a-5664-4007-8270-49b5dff8bae9" ---- -==== diff --git a/modules/kmm-gathering-data-for-kmm.adoc b/modules/kmm-gathering-data-for-kmm.adoc index f69ed0cb268e..c1c098ec72d9 100644 --- a/modules/kmm-gathering-data-for-kmm.adoc +++ b/modules/kmm-gathering-data-for-kmm.adoc @@ -37,9 +37,9 @@ $ oc adm must-gather --image="${MUST_GATHER_IMAGE}" -- /usr/bin/gather $ oc logs -fn openshift-kmm deployments/kmm-operator-controller ---- + -.Example output +Example output: ++ [%collapsible] -==== [source,terminal] ---- I0228 09:36:37.352405 1 request.go:682] Waited for 1.001998746s due to client-side throttling, not priority and fairness, request: GET:https://172.30.0.1:443/apis/machine.openshift.io/v1beta1?timeout=32s @@ -70,4 +70,3 @@ I0228 09:36:40.787879 1 controller.go:185] kmm "msg"="Starting EventSource I0228 09:36:40.787905 1 controller.go:193] kmm "msg"="Starting Controller" "controller"="preflightvalidationocp" "controllerGroup"="kmm.sigs.x-k8s.io" "controllerKind"="PreflightValidationOCP" I0228 09:36:40.786489 1 controller.go:193] kmm "msg"="Starting Controller" "controller"="PodNodeModule" "controllerGroup"="" "controllerKind"="Pod" ---- -==== diff --git a/modules/kmm-hub-installing-kmm-hub-creating-resources.adoc b/modules/kmm-hub-installing-kmm-hub-creating-resources.adoc index 83f671e68682..ce5187d7bb4d 100644 --- a/modules/kmm-hub-installing-kmm-hub-creating-resources.adoc +++ b/modules/kmm-hub-installing-kmm-hub-creating-resources.adoc @@ -10,7 +10,7 @@ * If you want to install KMM-Hub programmatically, you can use the following resources to create the `Namespace`, `OperatorGroup` and `Subscription` resources: - ++ [source,yaml] ---- --- diff --git a/modules/kmm-hub-running-kmm-on-the-spoke.adoc b/modules/kmm-hub-running-kmm-on-the-spoke.adoc index 7dde3a5ec8c8..5f8836cdd460 100644 --- a/modules/kmm-hub-running-kmm-on-the-spoke.adoc +++ b/modules/kmm-hub-running-kmm-on-the-spoke.adoc @@ -8,10 +8,10 @@ After installing Kernel Module Management (KMM) on the spoke, no further action is required. Create a `ManagedClusterModule` object from the hub to deploy kernel modules on spoke clusters. -.Procedure - You can install KMM on the spokes cluster through a RHACM `Policy` object. In addition to installing KMM from the OperatorHub and running it in a lightweight spoke mode, the `Policy` configures additional RBAC required for the RHACM agent to be able to manage `Module` resources. +.Procedure + * Use the following RHACM policy to install KMM on spoke clusters: + [source.yaml] diff --git a/modules/kmm-installing-older-versions.adoc b/modules/kmm-installing-older-versions.adoc index 507041e03a05..d541d0427e1b 100644 --- a/modules/kmm-installing-older-versions.adoc +++ b/modules/kmm-installing-older-versions.adoc @@ -130,7 +130,8 @@ $ oc create -f kmm-sub.yaml $ oc get -n openshift-kmm deployments.apps kmm-operator-controller ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME READY UP-TO-DATE AVAILABLE AGE diff --git a/modules/kmm-installing-using-cli.adoc b/modules/kmm-installing-using-cli.adoc index bbf0fd5c8c83..8d8ef9150bcf 100644 --- a/modules/kmm-installing-using-cli.adoc +++ b/modules/kmm-installing-using-cli.adoc @@ -73,7 +73,8 @@ $ oc create -f kmm-sub.yaml $ oc get -n openshift-kmm deployments.apps kmm-operator-controller ---- + -.Example output +Example output: ++ [source,terminal] ---- NAME READY UP-TO-DATE AVAILABLE AGE diff --git a/modules/kmm-observing-events.adoc b/modules/kmm-observing-events.adoc index a4c8889eff9e..1d2f81d9b40e 100644 --- a/modules/kmm-observing-events.adoc +++ b/modules/kmm-observing-events.adoc @@ -8,7 +8,6 @@ Use the following methods to view KMM events. -[discrete] [id="kmm-observing-events-build-and-sign_{context}"] == Build & sign @@ -27,7 +26,6 @@ Events: Normal SignSucceeded 57s kmm Sign job succeeded for kernel 6.6.2-201.fc39.x86_64 ---- -[discrete] [id="kmm-observing-events-module-load-unload_{context}"] == Module load or unload diff --git a/modules/kmm-reading-operator-logs.adoc b/modules/kmm-reading-operator-logs.adoc index c20538d8074b..741f33e5bd4d 100644 --- a/modules/kmm-reading-operator-logs.adoc +++ b/modules/kmm-reading-operator-logs.adoc @@ -8,29 +8,29 @@ You can use the `oc logs` command to read Operator logs, as in the following examples. -.Example command for KMM controller - +Example command for KMM controller:: ++ [source,terminal] ---- $ oc logs -fn openshift-kmm deployments/kmm-operator-controller ---- -.Example command for KMM webhook server - +Example command for KMM webhook server:: ++ [source,terminal] ---- $ oc logs -fn openshift-kmm deployments/kmm-operator-webhook-server ---- -.Example command for KMM-Hub controller - +Example command for KMM-Hub controller:: ++ [source,terminal] ---- $ oc logs -fn openshift-kmm-hub deployments/kmm-operator-hub-controller ---- -.Example command for KMM-Hub webhook server - +Example command for KMM-Hub webhook server:: ++ [source,terminal] ---- $ oc logs -fn openshift-kmm deployments/kmm-operator-hub-webhook-server diff --git a/modules/kmm-running-depmod.adoc b/modules/kmm-running-depmod.adoc index dedcbf94c529..115805b98fe9 100644 --- a/modules/kmm-running-depmod.adoc +++ b/modules/kmm-running-depmod.adoc @@ -24,9 +24,9 @@ $ depmod -b /opt ${KERNEL_FULL_VERSION}+`. ---- [id="example-dockerfile_{context}"] -== Example Dockerfile - -If you are building your image on {product-title}, consider using the Driver Tool Kit (DTK). +.Example Dockerfile +==== +If you are building your image on {product-title}, consider using the Driver Toolkit (DTK). For further information, see link:https://cloud.redhat.com/blog/how-to-use-entitled-image-builds-to-build-drivercontainers-with-ubi-on-openshift[using an entitled build]. @@ -52,3 +52,4 @@ data: 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} ---- +==== diff --git a/modules/kmm-signing-a-prebuilt-driver-container.adoc b/modules/kmm-signing-a-prebuilt-driver-container.adoc index 45c9dd62884d..39375d1fec48 100644 --- a/modules/kmm-signing-a-prebuilt-driver-container.adoc +++ b/modules/kmm-signing-a-prebuilt-driver-container.adoc @@ -54,5 +54,4 @@ spec: selector: kubernetes.io/arch: amd64 ---- - <1> `modprobe` - The name of the kmod to load. diff --git a/modules/kmm-signing-kmods-in-a-prebuilt-image.adoc b/modules/kmm-signing-kmods-in-a-prebuilt-image.adoc index bd5a682e5bb4..cf66148609bd 100644 --- a/modules/kmm-signing-kmods-in-a-prebuilt-image.adoc +++ b/modules/kmm-signing-kmods-in-a-prebuilt-image.adoc @@ -53,7 +53,6 @@ spec: selector: kubernetes.io/arch: amd64 ---- - <1> The name of the kmod to load. <2> The name of the container image. For example, `quay.io/myuser/my-driver: The name of the unsigned image. For example, `quay.io/myuser/my-driver: *Installed Operators* to locate and uninstall the Operator. - ++ [NOTE] ==== Alternatively, you can delete the `Subscription` resource in the KMM namespace. diff --git a/modules/kmm-using-driver-toolkit.adoc b/modules/kmm-using-driver-toolkit.adoc index c12e7f986871..36d81de672a7 100644 --- a/modules/kmm-using-driver-toolkit.adoc +++ b/modules/kmm-using-driver-toolkit.adoc @@ -10,10 +10,10 @@ The Driver Toolkit (DTK) is a convenient base image for building build kmod loader images. It contains tools and libraries for the OpenShift version currently running in the cluster. -.Procedure - Use DTK as the first stage of a multi-stage Dockerfile. +.Procedure + . Build the kernel modules. . Copy the `.ko` files into a smaller end-user image such as https://catalog.redhat.com/software/containers/ubi9/ubi-minimal[`ubi-minimal`]. diff --git a/modules/kmm-using-intree-modules.adoc b/modules/kmm-using-intree-modules.adoc index aaa43e32267f..9531d4f6efa8 100644 --- a/modules/kmm-using-intree-modules.adoc +++ b/modules/kmm-using-intree-modules.adoc @@ -10,6 +10,7 @@ In some cases, you might need to configure the KMM Module to avoid loading an out-of-tree kernel module and instead use the in-tree module, running only the device plugin. In such cases, you can omit the `moduleLoader` parameter from the `Module` custom resource (CR), and leave only the `devicePlugin` section, as shown in the following example. .Example `Module` CR +==== [source,yaml] ---- apiVersion: kmm.sigs.x-k8s.io/v1beta1 @@ -22,4 +23,5 @@ spec: devicePlugin: container: image: some.registry/org/my-device-plugin:latest ----- \ No newline at end of file +---- +==== diff --git a/modules/kmm-using-signing-with-kmm.adoc b/modules/kmm-using-signing-with-kmm.adoc index 0ba052b5fafc..c1189be9e5c2 100644 --- a/modules/kmm-using-signing-with-kmm.adoc +++ b/modules/kmm-using-signing-with-kmm.adoc @@ -10,7 +10,8 @@ On a Secure Boot enabled system, all kernel modules (kmods) must be signed with For more details on using Secure Boot, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/managing_monitoring_and_updating_the_kernel/signing-a-kernel-and-modules-for-secure-boot_managing-monitoring-and-updating-the-kernel#generating-a-public-and-private-key-pair_signing-a-kernel-and-modules-for-secure-boot[Generating a public and private key pair] -.Prerequisites +[id="kmm-using-signing-with-kmm-prerequisites_{context}"] +== Prerequisites * A public private key pair in the correct (DER) format. * At least one secure-boot enabled node with the public key enrolled in its MOK database. diff --git a/modules/kmm-validation-status.adoc b/modules/kmm-validation-status.adoc index 2f23456c1d0e..d4878f0a93e8 100644 --- a/modules/kmm-validation-status.adoc +++ b/modules/kmm-validation-status.adoc @@ -14,11 +14,13 @@ A `PreflightValidationOCP` resource reports the status and progress of each modu `statusReason`:: Verbal explanation regarding the status. -`verificationStage`:: Describes the validation stage being executed: + +`verificationStage`:: Describes the validation stage being executed: + * `Image`: Image existence verification * `Done`: Verification is done -`verificationStatus`:: The status of the Module verification: + +`verificationStatus`:: The status of the Module verification: + * `Success`: Verified * `Failure`: Verification failed * `InProgress`: Verification is in progress