TELCODOCS-2197: Add support for user defined tolerances to modules.

Author: StephenJamesSmith

hardware_enablement/kmm-kernel-module-management.adoc

@@ -104,6 +104,13 @@ include::modules/kmm-building-and-signing-a-kmod-image.adoc[leveloffset=+1]
 .Additional resources
 * link:https://docs.openshift.com/container-platform/4.12/authentication/understanding-and-creating-service-accounts.html#service-accounts-managing_understanding-service-accounts[Creating service accounts]
 
+// Added for TELCODOCS-2197
+include::modules/kmm-using-tolerations-for-kernel-module-scheduling.adoc[leveloffset=+1]
+include::modules/kmm-applying-tolerations-to-kernel-module-pods.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+* link:https://docs.openshift.com/container-platform/4.17/nodes/scheduling/nodes-scheduler-taints-tolerations.html#nodes-scheduler-taints-tolerations-about_nodes-scheduler-taints-tolerations[Understanding taints and tolerations]
+
 // Added for TELCODOCS-1109
 include::modules/kmm-hub-hub-and-spoke.adoc[leveloffset=+1]
 [role="_additional-resources"]

modules/kmm-applying-tolerations-to-kernel-module-pods.adoc

@@ -0,0 +1,68 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/kmm-kernel-module-management.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="kmm-applying-tolerations-to-kernel-module-pods_{context}"]
+= Applying tolerations to kernel module pods 
+
+Taints and tolerations consist of `effect`, `key`, and `value` parameters. Tolerations include additional `operator` and `tolerationSeconds` parameters. 
+
+`effect`:: Indicates the taint effect to match. If left empty, all taint effects are matched. When you set `effect`, valid values are: `NoSchedule`, `PreferNoSchedule`, or `NoExecute`.
+
+`key`:: The taint key that the toleration applies to. If left empty, all taint keys are matched. If the `key` is empty, you must set the `operator` parameter to `Exists`. This combination matches all values and all keys.
+
+`value`:: The taint value the toleration matches to. If the `operator` parameter is `Exists`, the value must be empty, otherwise use a regular string.
+
+`operator`:: Represents a relationship of a key to the value. Valid `operator` parameters are `Exists` and `Equal`. The default value is `Equal`. `Exists` is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category.
+
+`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.
+
+.Example taint in a node specification
+[source,yaml]
+----
+apiVersion: v1
+kind: Node
+metadata:
+  name: <my_node>
+#...
+spec:
+  taints:
+  - effect: NoSchedule
+    key: key1
+    value: value1
+#...
+----
+
+.Example toleration in a module specification
+[source,yaml]
+----
+apiVersion: kmm.sigs.x-k8s.io/v1beta1
+kind: Module
+metadata:
+  name: <my_kmod>
+spec:
+  ...
+  tolerations:
+    effect: NoSchedule
+    key: key1
+    operator: Equal
+    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.

modules/kmm-using-tolerations-for-kernel-module-scheduling.adoc

@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * hardware_enablement/kmm-kernel-module-management.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="kmm-using-tolerations-for-kernel-module-scheduling_{context}"]
+= Using tolerations for kernel module scheduling
+
+There are circumstances where you need to evacuate workloads on a node before upgrading a kernel module, which you can do through taints. You can use a taint to schedule only pods that contain a matching toleration on the node.
+
+However, you also need to set tolerations to allow Kernel Module Management (KMM) pods that run housekeeping operations, such as kernel module upgrades. The tolerations must match the taint that is added to the nodes.
+
+You can create user-defined tolerations to kernel modules to schedule selected KMM pods on a cordoned node. For example, during a device driver upgrade you cordon a node, at the same time, you can run housekeeping pods that perform the driver upgrades.
+
+The `ModuleSpec` field is used to carry the tolerations to the KMM pods that are used during pod creation.