Merge pull request #19852 from bg-chun/topology-manager

fix inaccurate information of topology-manager admin guide

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

@@ -6,6 +6,7 @@ reviewers:
 - klueska
 - lmdaly
 - nolancon
+- bg-chun
 
 content_template: templates/task
 min-kubernetes-server-version: v1.18
@@ -13,7 +14,7 @@ min-kubernetes-server-version: v1.18
 
 {{% capture overview %}}
 
-{{< feature-state state="beta" >}}
+{{< feature-state state="beta" for_k8s_version="v1.18" >}}
 
 An increasing number of systems leverage a combination of CPUs and hardware accelerators to support latency-critical execution and high-throughput parallel computation. These include workloads in fields such as telecommunications, scientific computing, machine learning, financial services and data analytics. Such hybrid systems comprise a high performance environment.
 
@@ -53,11 +54,16 @@ Support for the Topology Manager requires `TopologyManager` [feature gate](/docs
 
 The Topology Manager currently:
 
- - Works on Nodes with the `static` CPU Manager Policy enabled. See [control CPU Management Policies](/docs/tasks/administer-cluster/cpu-management-policies/)
- - Works on Pods making CPU requests or Device requests via extended resources
+ - Aligns Pods of all QoS classes.
+ - Aligns the requested resources that Hint Provider provides topology hints for.
 
 If these conditions are met, Topology Manager will align the requested resources.
 
+{{< note >}}
+To align CPU resources with other requested resources in a Pod Spec, the CPU Manager should be enabled and proper CPU Manager policy should be configured on a Node. See [control CPU Management Policies](/docs/tasks/administer-cluster/cpu-management-policies/).
+{{< /note >}}
+
+
 Topology Manager supports four allocation policies. You can set a policy via a Kubelet flag, `--topology-manager-policy`.
 There are four supported policies:
 
@@ -72,7 +78,7 @@ This is the default policy and does not perform any topology alignment.
 
 ### best-effort policy {#policy-best-effort}
 
-For each container in a Guaranteed Pod, kubelet, with `best-effort` topology 
+For each container in a Pod, the kubelet, with `best-effort` topology 
 management policy, 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, 
@@ -83,7 +89,7 @@ resource allocation decision.
 
 ### restricted policy {#policy-restricted}
 
-For each container in a Guaranteed Pod, kubelet, with `restricted` topology 
+For each container in a Pod, the kubelet, with `restricted` topology 
 management policy, 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, 
@@ -97,7 +103,7 @@ resource allocation decision.
 
 ### single-numa-node policy {#policy-single-numa-node}
 
-For each container in a Guaranteed Pod, kubelet, with `single-numa-node` topology 
+For each container in a Pod, the kubelet, with `single-numa-node` topology 
 management policy, 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, Topology Manager will store this and the *Hint Providers* can then use this information when making the 
@@ -135,8 +141,7 @@ spec:
 
 This pod runs in the `Burstable` QoS class because requests are less than limits.
 
-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 consider these Pod specifications. The Topology Manager would consult the Hint Providers to get topology hints. In the case of the `static`, the CPU Manager policy would return default topology hint, because these Pods do not have explicity request CPU resources.
 
 
 ```yaml
@@ -155,7 +160,26 @@ spec:
         example.com/device: "1"
 ```
 
-This pod runs in the `Guaranteed` QoS class because `requests` are equal to `limits`.
+This pod with integer CPU request runs in the `Guaranteed` QoS class because `requests` are equal to `limits`.
+
+
+```yaml
+spec:
+  containers:
+  - name: nginx
+    image: nginx
+    resources:
+      limits:
+        memory: "200Mi"
+        cpu: "300m"
+        example.com/device: "1"
+      requests:
+        memory: "200Mi"
+        cpu: "300m"
+        example.com/device: "1"
+```
+
+This pod with sharing CPU request runs in the `Guaranteed` QoS class because `requests` are equal to `limits`.
 
 
 ```yaml
@@ -173,10 +197,15 @@ spec:
 ```
 This pod runs in the `BestEffort` QoS class because there are no CPU and memory requests.
 
-The Topology Manager would consider both of the above pods. The Topology Manager would consult the Hint Providers, which are CPU and Device Manager to get topology hints for the pods. 
-In the case of the `Guaranteed` pod the `static` CPU Manager policy would return hints relating to the CPU request and the Device Manager would send back hints for the requested device.
+The Topology Manager would consider the above pods. The Topology Manager would consult the Hint Providers, which are CPU and Device Manager to get topology hints for the pods. 
 
-In the case of the `BestEffort` pod the CPU Manager would send back the default hint as there is no CPU request and the Device Manager would send back the hints for each of the requested devices.
+In the case of the `Guaranteed` pod with integer CPU request, the `static` CPU Manager policy would return topology hints relating to the exclusive CPU and the Device Manager would send back hints for the requested device.
+
+In the case of the `Guaranteed` pod with sharing CPU request, the `static` CPU Manager policy would return default topology hint as there is no exclusive CPU request and the Device Manager would send back hints for the requested device.
+
+In the above two cases of the `Guaranteed` pod, the `none` CPU Manager policy would return default topology hint.
+
+In the case of the `BestEffort` pod, the `static` CPU Manager policy would send back the default topology hint as there is no CPU request and the Device Manager would send back the hints for each of the requested devices.
 
 Using this information the Topology Manager calculates the optimal hint for the pod and stores this information, which will be used by the Hint Providers when they are making their resource assignments.