Merge pull request #104729 from openshift-cherrypick-robot/cherry-pick-104459-to-enterprise-4.21

[enterprise-4.21] TELCODOCS-2489: Adding housekeeping value for irq  pod annotation

modules/cnf-disabling-interrupt-processing-for-individual-pods.adoc

@@ -4,21 +4,88 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="cnf-disabling-interrupt-processing-for-individual-pods_{context}"]
-= Disabling interrupt processing for CPUs where pinned containers are running
+= Configuring interrupt processing for individual pods
 
-To achieve low latency for workloads, some containers require that the CPUs they are pinned to do not process device interrupts. A pod annotation, `irq-load-balancing.crio.io`, is used to define whether device interrupts are processed or not on the CPUs where the pinned containers are running. When configured, CRI-O disables device interrupts where the pod containers are running.
+To achieve low latency for workloads, some containers require that the CPUs they are pinned to do not process device interrupts. You can use the `irq-load-balancing.crio.io` pod annotation to control whether device interrupts are processed on CPUs where the pinned containers are running.
 
-To disable interrupt processing for CPUs where containers belonging to individual pods are pinned, ensure that `globallyDisableIrqLoadBalancing` is set to `false` in the performance profile. Then, in the pod specification, set the `irq-load-balancing.crio.io` pod annotation to `disable`.
+The annotation supports the following values:
 
-The following pod specification contains this annotation:
+`disable`:: Disables IRQ load balancing for all CPUs allocated to the container. Use this value for latency-sensitive workloads when you want to exclude container CPUs from interrupt handling.
+
+`housekeeping`:: Preserves IRQ handling on the first CPU that is allocated to the container, including that CPU's thread siblings. The subsequent CPUs allocated to the container are excluded from interrupt processing. This configuration also injects the `OPENSHIFT_HOUSEKEEPING_CPUS` environment variable into the container. Use this variable to see which CPUs are designated for housekeeping tasks. 
++
+You can use the `housekeeping` value to reduce the overall CPU footprint by allowing a small subset of container CPUs to handle both application housekeeping work and system interrupts.
+
+[NOTE]
+====
+When using the `housekeeping` value, the CPUs designated for housekeeping handle interrupts for the entire system.
+====
+
+.Prerequisites
+
+* You configured a performance profile for the node.
+* You set the `globallyDisableIrqLoadBalancing` field to `false` in the performance profile.
+
+.Procedure
+
+. Create the `Pod` resource and configure the `irq-load-balancing.crio.io` annotation:
++
+.Example pod specification
 [source,yaml]
 ----
-apiVersion: performance.openshift.io/v2
+apiVersion: v1
 kind: Pod
 metadata:
+  name: dpdk-workload
   annotations:
-      irq-load-balancing.crio.io: "disable"
+    irq-load-balancing.crio.io: "disable"
 spec:
-    runtimeClassName: performance-<profile_name>
-...
+  runtimeClassName: performance-<profile_name>
+  containers:
+  - name: app
+    image: example-image
+    resources:
+      requests:
+        cpu: "8"
+        memory: "4Gi"
+      limits:
+        cpu: "8"
+        memory: "4Gi"
 ----
++
+* `annotations.irq-load-balancing.crio.io` defines whether device interrupts are processed on the container CPUs. Set to `disable` to prevent all container CPUs from handling IRQs, or set to `housekeeping` to allow the first allocated CPU and its thread siblings to handle IRQs while excluding the remaining CPUs from IRQ handling.
+* `spec.runtimeClassName` sets the runtime class to the performance profile. Replace `<profile_name>` with the name of your performance profile.
+
+. Apply the `Pod` resource by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f pod.yaml
+----
+
+.Verification
+
+. Verify the CPUs assigned to the pod:
++
+[source,terminal]
+----
+$ oc exec <pod_name> -- cat /sys/fs/cgroup/cpuset.cpus
+----
+
+. For pods using the `housekeeping` annotation, verify the housekeeping CPU environment variable:
++
+[source,terminal]
+----
+$ oc exec <pod_name> -- printenv OPENSHIFT_HOUSEKEEPING_CPUS
+----
++
+Replace `<pod_name>` with the name of the pod.
+
+. On the worker node, verify the CPUs excluded from IRQ handling:
++
+[source,terminal]
+----
+$ grep IRQBALANCE_BANNED_CPUS /etc/sysconfig/irqbalance
+----
++
+The output is a hexadecimal bitmask representing the CPUs excluded from IRQ handling.