From 5eaa91fda2400eeddd7a90e1fa3fc72f3716eff7 Mon Sep 17 00:00:00 2001
From: Ashleigh Brennan <abrennan@redhat.com>
Date: Wed, 5 Nov 2025 10:20:19 -0600
Subject: [PATCH] CNV-70994: Add CPU manager / pinning docs for CNV

---
 _topic_maps/_topic_map.yml                    |  2 +
 modules/virt-CPU-manager-policy.adoc          | 75 +++++++++++++++++++
 .../virt-perf-optimization.adoc               | 12 +++
 3 files changed, 89 insertions(+)
 create mode 100644 modules/virt-CPU-manager-policy.adoc
 create mode 100644 virt/post_installation_configuration/virt-perf-optimization.adoc

diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
index 69bcad9e4b..a8ed6e4140 100644
--- a/_topic_maps/_topic_map.yml
+++ b/_topic_maps/_topic_map.yml
@@ -4790,6 +4790,8 @@ Topics:
     File: virt-post-install-network-config
   - Name: Storage configuration
     File: virt-post-install-storage-config
+  - Name: Performance optimization
+    File: virt-perf-optimization
   - Name: Configuring higher VM workload density
     File: virt-configuring-higher-vm-workload-density
   - Name: Configuring certificate rotation
diff --git a/modules/virt-CPU-manager-policy.adoc b/modules/virt-CPU-manager-policy.adoc
new file mode 100644
index 0000000000..72984e6d93
--- /dev/null
+++ b/modules/virt-CPU-manager-policy.adoc
@@ -0,0 +1,75 @@
+// Module included in the following assemblies:
+//
+// * virt/post_installation_configuration/virt-perf-optimization.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="virt-CPU-manager-policy_{context}"]
+= Configuring full physical cores for virtual machines
+
+[role="_abstract"]
+As a cluster administrator, you can allocate a full physical core to a specific virtual machine (VM), instead of allowing different VMs to share the same physical core.
+Configuring your VMs to use only full physical cores can optimize performance for high-throughput or latency-critical VMs.
+
+Allocating only full physical cores is important on simultaneous multi-threading (SMT) enabled systems because it offers the following benefits:
+
+* Prevents noisy neighbors and resource contention
+* Mitigates performance degradation
+* Offers predictable latency
+* Guarantees exclusive CPU resources
+
+You can configure full physical core allocation by modifying the `cpuManagerPolicy` and `cpuManagerPolicyOptions` settings in the `KubeletConfig` custom resource (CR).
+
+.Prerequisites
+
+* You have cluster administrator access to a {product-title} cluster with {VirtProductName} installed.
+* You have installed the {oc-first}.
+* You have enabled CPU Manager on the node where your VM runs.
+
+.Procedure
+
+. Edit the `KubeletConfig` CR to add the required `cpuManagerPolicy` and `cpuManagerPolicyOptions` configurations:
++
+[source,yaml]
+----
+apiVersion: machineconfiguration.openshift.io/v1
+kind: KubeletConfig
+# ...
+cpuManagerPolicy: static
+cpuManagerPolicyOptions:
+  full-pcpus-only: true
+kubeReserved:
+  cpu: "1"
+# ...
+----
++
+* You must set the `cpuManagerPolicy: static` policy to enable exclusive CPU allocation. This setting is a prerequisite for configuring the `cpuManagerPolicyOptions` settings.
+* You must set the `full-pcpus-only: true` policy option so that the static CPU Manager policy only allocates full physical cores.
+* You must reserve 1 CPU for the system by setting `cpu: "1"` in the `kubeReserved` settings. This ensures that the cluster remains stable, by requiring that the system's core functions always have access to the CPU that they need to work correctly.
+
+. Run the following command to apply the changes to the `KubeletConfig` CR:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----
+
+.Verification
+
+* Inspect the kubelet configuration on a node where the change you applied the change, by running the following command and inspecting the output:
++
+[source,terminal]
+----
+$ oc debug node/<node_name> -- chroot /host cat /etc/kubernetes/kubelet.conf | grep -E -A 2 'cpuManagerPolicy|kubeReserved'
+----
++
+Example output:
++
+[source,YAML]
+----
+cpuManagerPolicy: static
+cpuManagerPolicyOptions:
+  full-pcpus-only: true
+--
+kubeReserved:
+  cpu: "1"
+----
diff --git a/virt/post_installation_configuration/virt-perf-optimization.adoc b/virt/post_installation_configuration/virt-perf-optimization.adoc
new file mode 100644
index 0000000000..9c9650c58d
--- /dev/null
+++ b/virt/post_installation_configuration/virt-perf-optimization.adoc
@@ -0,0 +1,12 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="virt-perf-optimization"]
+= Performance optimization
+:context: virt-perf-optimization
+
+toc::[]
+
+[role="_abstract"]
+You can modify certain configurations for your {VirtProductName} deployment to improve efficiency, cost-effectiveness, and reliability.
+
+include::modules/virt-CPU-manager-policy.adoc[leveloffset=+1]