update docs for prefer-align-cpus-by-uncorecache feature

Author: wongchar

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

@@ -268,6 +268,7 @@ The following policy options exist for the static `CPUManager` policy:
 * `distribute-cpus-across-numa` (alpha, hidden by default) (1.23 or higher)
 * `align-by-socket` (alpha, hidden by default) (1.25 or higher)
 * `distribute-cpus-across-cores` (alpha, hidden by default) (1.31 or higher)
+* `prefer-align-cpus-by-uncorecache` (alpha, hidden by default) (1.32 or higher)
 
 If the `full-pcpus-only` policy option is specified, the static policy will always allocate full physical cores.
 By default, without this option, the static policy allocates CPUs using a topology-aware best-fit allocation.
@@ -318,6 +319,20 @@ the benefit of reducing contention diminishes. Conversely, default behavior
 can help in reducing inter-core communication overhead, potentially providing
 better performance under high load conditions.
 
+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.
 
 The `full-pcpus-only` option can be enabled by adding `full-pcpus-only=true` to
 the CPUManager policy options.
@@ -334,3 +349,8 @@ The `distribute-cpus-across-cores` option can be enabled by adding
 `distribute-cpus-across-cores=true` to the `CPUManager` policy options.
 It cannot be used with `full-pcpus-only` or `distribute-cpus-across-numa` policy
 options together at this moment.
+
+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.