diff --git a/content/en/docs/concepts/policy/node-resource-managers.md b/content/en/docs/concepts/policy/node-resource-managers.md index 595c89c7d7..3c26ef3cec 100644 --- a/content/en/docs/concepts/policy/node-resource-managers.md +++ b/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" >}} diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/prefer-align-cpus-by-uncorecache.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/prefer-align-cpus-by-uncorecache.md new file mode 100644 index 0000000000..9914843dd8 --- /dev/null +++ b/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. diff --git a/content/en/docs/tasks/administer-cluster/cpu-management-policies.md b/content/en/docs/tasks/administer-cluster/cpu-management-policies.md index 0bc4196df3..95a257f281 100644 --- a/content/en/docs/tasks/administer-cluster/cpu-management-policies.md +++ b/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.