Merge pull request #48340 from wongchar/split-uncorecache-awareness

Add prefer-align-cpus-by-uncorecache feature gate

content/en/docs/concepts/policy/node-resource-managers.md

@@ -189,11 +189,15 @@ The following policy options exist for the static CPU management policy:
 `align-by-socket` (alpha, hidden by default)
 : Align CPUs by physical package / socket boundary, rather than logical NUMA boundaries (available since Kubernetes v1.25)
 `distribute-cpus-across-cores` (alpha, hidden by default)
-: allocate virtual cores, sometimes called hardware threads, across different physical cores  (available since Kubernetes v1.31)
+: Allocate virtual cores, sometimes called hardware threads, across different physical cores  (available since Kubernetes v1.31)
 `distribute-cpus-across-numa` (alpha, hidden by default)
-: spread CPUs across different NUMA domains, aiming for an even balance between the selected domains (available since Kubernetes v1.23)
+: Spread CPUs across different NUMA domains, aiming for an even balance between the selected domains (available since Kubernetes v1.23)
 `full-pcpus-only` (beta, visible by default)
 : Always allocate full physical cores (available since Kubernetes v1.22)
+`strict-cpu-reservation` (alpha, hidden by default)
+: Prevent all the pods regardless of their Quality of Service class to run on reserved CPUs (available since Kubernetes v1.32)
+`prefer-align-cpus-by-uncorecache` (alpha, hidden by default)
+: Align CPUs  by uncore (Last-Level) cache boundary on a best-effort way (available since Kubernetes v1.32)
 
 You can toggle groups of options on and off based upon their maturity level
 using the following feature gates:
@@ -273,6 +277,24 @@ of `reservedSystemCPUs` and cause host OS services to starve in real life deploy
 If the `strict-cpu-reservation` policy option is enabled, the static policy will not allow
 any workload to use the CPU cores specified in `reservedSystemCPUs`.
 
+##### `prefer-align-cpus-by-uncorecache`
+
+If the `prefer-align-cpus-by-uncorecache` policy is specified, the static policy
+will allocate CPU resources for individual containers such that all CPUs assigned 
+to a container share the same uncore cache block (also known as the Last-Level Cache 
+or LLC). By default, the `CPUManager` will tightly pack CPU assignments which can 
+result in containers being assigned CPUs from multiple uncore caches. This option 
+enables the `CPUManager` to allocate CPUs in a way that maximizes the efficient use 
+of the uncore cache. Allocation is performed on a best-effort basis, aiming to 
+affine as many CPUs as possible within the same uncore cache. If the container's 
+CPU requirement exceeds the CPU capacity of a single uncore cache, the `CPUManager` 
+minimizes the number of uncore caches used in order to maintain optimal uncore 
+cache alignment. Specific workloads can benefit in performance from the reduction 
+of inter-cache latency and noisy neighbors at the cache level. If the `CPUManager` 
+cannot align optimally while the node has sufficient resources, the container will 
+still be admitted using the default packed behavior.
+
+
 ## Memory Management Policies
 
 {{< feature-state feature_gate_name="MemoryManager" >}}

content/en/docs/reference/command-line-tools-reference/feature-gates/prefer-align-cpus-by-uncorecache.md

@@ -0,0 +1,13 @@
+---
+title: PreferAlignCpusByUncoreCache
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.32"
+---
+When `PreferAlignCpusByUncoreCache` is enabled while the CPU Manager Policy is set to `static`, containers within a `Guaranteed` pod will individually be aligned to an uncore cache group at a best-effort policy. This feature can optimize performance for certain cache-sensitive workloads by minimizing the cpu allocation across uncore caches.

content/en/docs/tasks/administer-cluster/cpu-management-policies.md

@@ -156,6 +156,7 @@ The following policy options exist for the static `CPUManager` policy:
 * `align-by-socket` (alpha, hidden by default) (1.25 or higher)
 * `distribute-cpus-across-cores` (alpha, hidden by default) (1.31 or higher)
 * `strict-cpu-reservation` (alpha, hidden by default) (1.32 or higher)
+* `prefer-align-cpus-by-uncorecache` (alpha, hidden by default) (1.32 or higher)
 
 The `full-pcpus-only` option can be enabled by adding `full-pcpus-only=true` to
 the CPUManager policy options.
@@ -176,5 +177,10 @@ options together at this moment.
 The `strict-cpu-reservation` option can be enabled by adding `strict-cpu-reservation=true` to
 the CPUManager policy options followed by removing the `/var/lib/kubelet/cpu_manager_state` file and restart kubelet.
 
+The `prefer-align-cpus-by-uncorecache` option can be enabled by adding the
+`prefer-align-cpus-by-uncorecache` to the `CPUManager` policy options. If 
+incompatible options are used, the kubelet will fail to start with the error 
+explained in the logs.
+
 For mode detail about the behavior of the individual options you can configure, please refer to the
 [Node ResourceManagers](/docs/concepts/policy/node-resource-managers) documentation.