topologymanager: document topology manager policy options

Signed-off-by: PiotrProkop <[email protected]>

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -196,6 +196,9 @@ For a reference to old feature gates that are removed, please refer to
 | `TopologyAwareHints` | `true` | Beta | 1.24 | |
 | `TopologyManager` | `false` | Alpha | 1.16 | 1.17 |
 | `TopologyManager` | `true` | Beta | 1.18 | |
+| `TopologyManagerPolicyAlphaOptions` | `false` | Alpha | 1.26 | |
+| `TopologyManagerPolicyBetaOptions` | `false` | Beta | 1.26 | |
+| `TopologyManagerPolicyOptions` | `false` | Alpha | 1.26 | |
 | `UserNamespacesStatelessPodsSupport` | `false` | Alpha | 1.25 | |
 | `VolumeCapacityPriority` | `false` | Alpha | 1.21 | - |
 | `WinDSR` | `false` | Alpha | 1.14 | |
@@ -727,6 +730,15 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `TopologyManager`: Enable a mechanism to coordinate fine-grained hardware resource
   assignments for different components in Kubernetes. See
   [Control Topology Management Policies on a node](/docs/tasks/administer-cluster/topology-manager/).
+- `TopologyManagerPolicyAlphaOptions`: This allow fine-tuning of topology manager policies,
+  experimental, Alpha-quality options.
+  This feature gate guards *a group* of topology manager options whose quality level is alpha.
+  This feature gate will never graduate to beta or stable.
+- `TopologyManagerPolicyBetaOptions`: This allow fine-tuning of topology manager policies,
+  experimental, Beta-quality options.
+  This feature gate guards *a group* of topology manager options whose quality level is alpha.
+  This feature gate will never graduate to stable.
+- `TopologyManagerPolicyOptions`: Allow fine-tuning of topology manager policies,
 - `UserNamespacesStatelessPodsSupport`: Enable user namespace support for stateless Pods.
 - `VolumeCapacityPriority`: Enable support for prioritizing nodes in different
   topologies based on available PV capacity.

content/en/docs/tasks/administer-cluster/topology-manager.md

@@ -213,6 +213,18 @@ reschedule the pod. It is recommended to use a Deployment with replicas to trigg
 the Pod.An external control loop could be also implemented to trigger a redeployment of pods
 that have the `Topology Affinity` error.
 
+### Topology manager policy options
+
+If the `prefer-closest-numa-nodes` policy option is specified, the `best-effort` and `restricted`
+policies will favor sets of NUMA nodes with shorter distance between nodes when making admission decisions.
+You can enable this option by adding `prefer-closest-numa-nodes=true` to the Topology Manager policy options.
+By default, without this option, Topology Manager align resources on either a single NUMA node or
+the minimum number of NUMA nodes (in cases where more than one NUMA node is required). However,
+the `TopologyManager` is not aware of NUMA distances and does not take them into account when making admission decisions.
+This limitation surfaces in multi-socket, as well as single-socket multi NUMA systems,
+and can cause significant performance degradation in latency-critical execution and high-throughput applications if the
+Topology Manager decides to align resources on non-adjacent NUMA nodes.
+
 ### Pod Interactions with Topology Manager Policies
 
 Consider the containers in the following pod specs:
@@ -330,4 +342,3 @@ assignments.
 
 2. The scheduler is not topology-aware, so it is possible to be scheduled on a node and then fail
    on the node due to the Topology Manager.
-