Merge pull request #95111 from amolnar-rh/OCPBUGS-54188

OCPBUGS-54188: Update Pod interactions with Topology Manager policies

Author: abhatt-rh

modules/pod-interactions-with-topology-manager.adoc

@@ -5,7 +5,7 @@
 [id="pod-interactions-with-topology-manager_{context}"]
 = Pod interactions with Topology Manager policies
 
-The example `Pod` specs below help illustrate pod interactions with Topology Manager.
+The example `Pod` specs illustrate pod interactions with Topology Manager.
 
 The following pod runs in the `BestEffort` QoS class because no resource requests or limits are specified.
 
@@ -32,9 +32,11 @@ spec:
         memory: "100Mi"
 ----
 
-If the selected policy is anything other than `none`, Topology Manager would not consider either of these `Pod` specifications.
+If the selected policy is anything other than `none`, Topology Manager would process all the pods and it enforces resource alignment only for the `Guaranteed` Qos `Pod` specification.
+When the Topology Manager policy is set to `none`, the relevant containers are pinned to any available CPU without considering NUMA affinity. This is the default behavior and it does not optimize for performance-sensitive workloads.
+Other values enable the use of topology awareness information from device plugins core resources, such as CPU and memory. The Topology Manager attempts to align the CPU, memory, and device allocations according to the topology of the node when the policy is set to other values than `none`. For more information about the available values, see _Topology Manager policies_.
 
-The last example pod below runs in the Guaranteed QoS class because requests are equal to limits.
+The following example pod runs in the `Guaranteed` QoS class because requests are equal to limits.
 
 [source,yaml]
 ----
@@ -53,6 +55,6 @@ spec:
         example.com/device: "1"
 ----
 
-Topology Manager would consider this pod. The Topology Manager would consult the hint providers, which are CPU Manager and Device Manager, to get topology hints for the pod.
+Topology Manager would consider this pod. The Topology Manager would consult the Hint Providers, which are the CPU Manager, the Device Manager, and the Memory Manager, to get topology hints for the pod.
 
-Topology Manager will use this information to store the best topology for this container. In the case of this pod, CPU Manager and Device Manager will use this stored information at the resource allocation stage.
+Topology Manager will use this information to store the best topology for this container. In the case of this pod, CPU Manager and Device Manager will use this stored information at the resource allocation stage.

modules/topology-manager-policies.adoc

@@ -3,7 +3,7 @@
 // * scaling_and_performance/using-topology-manager.adoc
 // * post_installation_configuration/node-tasks.adoc
 
-[id="topology_manager_policies_{context}"]
+[id="topology-manager-policies_{context}"]
 = Topology Manager policies
 
 Topology Manager aligns `Pod` resources of all Quality of Service (QoS) classes by collecting topology hints from Hint Providers, such as CPU Manager and Device Manager, and using the collected hints to align the `Pod` resources.
@@ -16,15 +16,14 @@ This is the default policy and does not perform any topology alignment.
 
 `best-effort` policy::
 
-For each container in a pod with the `best-effort` topology management policy, kubelet calls each Hint Provider to discover their resource
-availability. Using this information, the Topology Manager stores the preferred NUMA Node affinity for that container. If the affinity is not preferred, Topology Manager stores this and admits the pod to the node.
+For each container in a pod with the `best-effort` topology management policy, kubelet tries to align all the required resources on a NUMA node according to the preferred NUMA node affinity for that container. Even if the allocation is not possible due to insufficient resources, the Topology Manager still admits the pod but the allocation is shared with other NUMA nodes.
 
 `restricted` policy::
 
-For each container in a pod with the `restricted` topology management policy, kubelet calls each Hint Provider to discover their resource
-availability. Using this information, the Topology Manager stores the preferred NUMA Node affinity for that container. If the affinity is not
-preferred, Topology Manager rejects this pod from the node, resulting in a pod in a `Terminated` state with a pod admission failure.
+For each container in a pod with the `restricted` topology management policy, kubelet determines the theoretical minimum number of NUMA nodes that can fulfill the request. If the actual allocation requires more than the that number of NUMA nodes, the Topology Manager rejects the admission, placing the pod in a `Terminated` state. If the number of NUMA nodes can fulfill the request, the Topology Manager admits the pod and the pod starts running.
 
 `single-numa-node` policy::
 
-For each container in a pod with the `single-numa-node` topology management policy, kubelet calls each Hint Provider to discover their resource availability. Using this information, the Topology Manager determines if a single NUMA Node affinity is possible. If it is, the pod is admitted to the node. If a single NUMA Node affinity is not possible, the Topology Manager rejects the pod from the node. This results in a pod in a Terminated state with a pod admission failure.
+For each container in a pod with the `single-numa-node` topology management policy, kubelet admits the pod if all the resources required by the pod can be allocated on the same NUMA node. If a single NUMA node affinity is not possible, the Topology Manager rejects the pod from the node. This results in a pod in a `Terminated` state with a pod admission failure.
+
+

scalability_and_performance/telco-core-rds.adoc

@@ -174,7 +174,7 @@ include::modules/telco-core-scheduling.adoc[leveloffset=+2]
 
 * xref:../scalability_and_performance/cnf-numa-aware-scheduling.adoc#cnf-numa-aware-scheduling[Scheduling NUMA-aware workloads]
 
-* xref:../scalability_and_performance/using-cpu-manager.adoc#topology_manager_policies_using-cpu-manager-and-topology_manager[Topology Manager policies]
+* xref:../scalability_and_performance/using-cpu-manager.adoc#topology-manager-policies_using-cpu-manager-and-topology-manager[Topology Manager policies]
 
 include::modules/telco-core-node-configuration.adoc[leveloffset=+2]
 

scalability_and_performance/using-cpu-manager.adoc

@@ -2,7 +2,7 @@
 [id='using-cpu-manager']
 = Using CPU Manager and Topology Manager
 include::_attributes/common-attributes.adoc[]
-:context: using-cpu-manager-and-topology_manager
+:context: using-cpu-manager-and-topology-manager
 
 toc::[]
 
@@ -31,3 +31,8 @@ include::modules/topology-manager-policies.adoc[leveloffset=+1]
 include::modules/setting-up-topology-manager.adoc[leveloffset=+1]
 
 include::modules/pod-interactions-with-topology-manager.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../scalability_and_performance/using-cpu-manager.adoc#topology-manager-policies_using-cpu-manager-and-topology-manager[Topology Manager policies]