Merge pull request #96020 from jhradilek/kmm-dita-prep

abhatt-rh · web-flow · commit c9acc56a4f5f · 2025-08-01T16:30:05.000+01:00
Updated KMM Operator modules to pass DITA validation
diff --git 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.
+====
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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:<kernelversion`.
 <3> The name of the unsigned image. For example, `quay.io/myuser/my-driver:<kernelversion`.
diff --git a/modules/kmm-uninstalling-kmmo-red-hat-catalog.adoc b/modules/kmm-uninstalling-kmmo-red-hat-catalog.adoc
@@ -8,10 +8,8 @@ Use this procedure if KMM was installed from the Red Hat catalog.
 
 .Procedure
 
-Use the following method to uninstall the KMM Operator:
-
 * Use the OpenShift console under *Operators* --> *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
@@ -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
@@ -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
-----
+----
+====
diff --git 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
@@ -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
