From c1d0fa8883a52a65954006bd5692a5f3ae8ce660 Mon Sep 17 00:00:00 2001
From: Alexey Perevalov <alexey.perevalov@huawei.com>
Date: Wed, 14 Oct 2020 14:29:11 +0300
Subject: [PATCH] Actuallize podresources description

This commit updates description according to
https://github.com/kubernetes/enhancements/pull/1884

Signed-off-by: Alexey Perevalov <alexey.perevalov@huawei.com>
---
 .../compute-storage-net/device-plugins.md     | 79 ++++++++++++++++++-
 1 file changed, 78 insertions(+), 1 deletion(-)

diff --git a/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md b/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md
index 441d3bd871d6d..13ff0dc079fb9 100644
--- a/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md
+++ b/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md
@@ -193,6 +193,83 @@ for these devices:
 // node resources consumed by pods and containers on the node
 service PodResourcesLister {
     rpc List(ListPodResourcesRequest) returns (ListPodResourcesResponse) {}
+    rpc GetAllocatableResources(AllocatableResourcesRequest) returns (AllocatableResourcesResponse) {}
+    rpc Watch(WatchPodResourcesRequest) returns (stream WatchPodResourcesResponse) {}
+}
+```
+
+List endpoint provides information on resources of running pods with details such as
+id of exclusively allocated CPUs, device id as it was reported by device plugins and id of
+NUMA node where these devices are allocated.
+
+```gRPC
+// ListPodResourcesResponse is the response returned by List function
+message ListPodResourcesResponse {
+    repeated PodResources pod_resources = 1;
+}
+
+// PodResources contains information about the node resources assigned to a pod
+message PodResources {
+    string name = 1;
+    string namespace = 2;
+    repeated ContainerResources containers = 3;
+}
+
+// ContainerResources contains information about the resources assigned to a container
+message ContainerResources {
+    string name = 1;
+    repeated ContainerDevices devices = 2;
+    repeated int64 cpu_ids = 3;
+}
+
+// Topology describes hardware topology of the resource
+message TopologyInfo {
+        repeated NUMANode nodes = 1;
+}
+
+// NUMA representation of NUMA node
+message NUMANode {
+        int64 ID = 1;
+}
+
+// ContainerDevices contains information about the devices assigned to a container
+message ContainerDevices {
+    string resource_name = 1;
+    repeated string device_ids = 2;
+    TopologyInfo topology = 3;
+}
+```
+
+GetAllocatableResources provides information on resources initially available on the worker node.
+It provides more information than kubelet exports to APIServer.
+
+```gRPC
+// AvailableResourcesResponses contains information about all the devices known by the kubelet
+message AllocatableResourcesResponse {
+    repeated ContainerDevices devices = 1;
+    repeated int64 cpu_ids = 2;
+}
+
+```
+
+Watch intends to quickly obtain information on a newly launched pod, the information obtained is the same
+as obtained by List. By using Watch endpoint Monitoring agents do not need to call List periodically anymore.
+
+```gRPC
+
+// WatchPodResourcesRequest is the request made to the Watch PodResourcesLister service
+message WatchPodResourcesRequest {}
+
+enum WatchPodAction {
+    ADDED = 0;
+    DELETED = 1;
+}
+
+// WatchPodResourcesResponse is the response returned by Watch function
+message WatchPodResourcesResponse {
+    WatchPodAction action = 1;
+    string uid = 2;
+    repeated PodResources pod_resources = 3;
 }
 ```
 
@@ -204,7 +281,7 @@ DaemonSet, `/var/lib/kubelet/pod-resources` must be mounted as a
 {{< glossary_tooltip term_id="volume" >}} in the plugin's
 [PodSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core).
 
-Support for the "PodResources service" requires `KubeletPodResources` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to be enabled. It is enabled by default starting with Kubernetes 1.15.
+Support for the "PodResourcesLister service" requires `KubeletPodResources` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to be enabled. It is enabled by default starting with Kubernetes 1.15.
 
 ## Device Plugin integration with the Topology Manager