add an example for api

Signed-off-by: Zhang Kang <kang.zhang@intel.com>
koordinator-sh · Jan 18, 2024 · ed626e2 · ed626e2
1 parent b988544
commit ed626e2
Showing 1 changed file with 49 additions and 32 deletions.
diff --git a/docs/proposals/koordlet/20231227-koordlet-resctrl-qos-enhance.md b/docs/proposals/koordlet/20231227-koordlet-resctrl-qos-enhance.md
@@ -14,35 +14,43 @@ last-updated: 2023-12-28
 # Resctrl QoS Enhancement
 
 ## Table of Contents
+=================
+
 * [Resctrl QoS Enhancement](#resctrl-qos-enhancement)
-   * [Table of Contents](#table-of-contents)
-* [Table of Contents](#table-of-contents-1)
-   * [Glossary](#glossary)
-   * [Summary](#summary)
-   * [Motivation](#motivation)
-      * [Goals](#goals)
-      * [Non-Goals/Future Work](#non-goalsfuture-work)
-   * [Proposal](#proposal)
-      * [User Stories](#user-stories)
-         * [Story 1](#story-1)
-         * [Story 2](#story-2)
-         * [Story 3](#story-3)
-         * [Story 4](#story-4)
-      * [Requirements (Optional)](#requirements-optional)
-         * [Functional Requirements](#functional-requirements)
-            * [FR1](#fr1)
-            * [FR2](#fr2)
-         * [Non-Functional Requirements](#non-functional-requirements)
-            * [NFR1](#nfr1)
-            * [NFR2](#nfr2)
-      * [API](#api)
-      * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
-      * [Risks and Mitigations](#risks-and-mitigations)
-   * [Alternatives](#alternatives)
-   * [Upgrade Strategy](#upgrade-strategy)
-   * [Additional Details](#additional-details)
-      * [Test Plan [optional]](#test-plan-optional)
-   * [Implementation History](#implementation-history)
+    * [Table of Contents](#table-of-contents)
+    * [Glossary](#glossary)
+    * [Summary](#summary)
+    * [Motivation](#motivation)
+        * [Goals](#goals)
+        * [Non-Goals/Future Work](#non-goalsfuture-work)
+    * [Proposal](#proposal)
+        * [User Stories](#user-stories)
+            * [Story 1](#story-1)
+            * [Story 2](#story-2)
+            * [Story 3](#story-3)
+            * [Story 4](#story-4)
+        * [Requirements (Optional)](#requirements-optional)
+            * [Functional Requirements](#functional-requirements)
+                * [FR1](#fr1)
+                * [FR2](#fr2)
+            * [Non-Functional Requirements](#non-functional-requirements)
+                * [NFR1](#nfr1)
+                * [NFR2](#nfr2)
+        * [API](#api)
+        * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
+            * [Resctrl Runtime Hook Plugin](#resctrl-runtime-hook-plugin)
+                * [Resctrl Runtime Hook Plugin Init](#resctrl-runtime-hook-plugin-init)
+                * [Pod Level LLC/MBA](#pod-level-llcmba)
+                * [Fixed Class Level LLC/MBA](#fixed-class-level-llcmba)
+                * [Exsiting Pod](#exsiting-pod)
+            * [Resctrl Metrics Collector](#resctrl-metrics-collector)
+        * [Evaluation and Observability](#evaluation-and-observability)
+        * [Risks and Mitigations](#risks-and-mitigations)
+    * [Alternatives](#alternatives)
+    * [Upgrade Strategy](#upgrade-strategy)
+    * [Additional Details](#additional-details)
+        * [Test Plan [optional]](#test-plan-optional)
+    * [Implementation History](#implementation-history)
 
 ## Glossary
 
@@ -124,14 +132,23 @@ considerations for performance, reliability and security.
 ##### NFR2
 
 ### API
-To support pod level LLC/MBA limit, we add a new annotation, the annotation key is `node.koordinator.sh/resctrl`, the annotation value is defined as below:
+To support pod level LLC/MBA limit, we add a new annotation, the annotation key is `node.koordinator.sh/resctrl`, the annotation value finally will be parsed as below:
 ```go
 type Resctrl struct {
     L3 map[int64]int64
     MB map[int64]int64
 }
 ```
 
+Below is the example of annotation. 80 means 80% of LLC. 60 means 60% of MB.
+
+```go
+{
+  "L3": "80"
+  "MB": "60"
+}
+```
+
 ### Implementation Details/Notes/Constraints
 
 To achieve fine-grained control and monitoring of LLC and MBA resources, we propose the implementation of a two-pronged approach:
@@ -157,8 +174,8 @@ To achieve fine-grained control and monitoring of LLC and MBA resources, we prop
 
 
 ##### Fixed Class Level LLC/MBA
-1. Subscribe RunPodSanbox, if pod without annotation `node.koordinator.sh/resctrl`, RDTEngine will just record this pod
-2. Subscribe CreateContainer, resctrl runtime hook will get closid and runc prestart hook from ResctrlEngine
+1. Subscribe RunPodSanbox, if pod without annotation `node.koordinator.sh/resctrl`, ResctrlEngine will record this pod.
+2. Subscribe CreateContainer, resctrl runtime hook will get closid and runc prestart hook from ResctrlEngine, and then update ContainerContext, leverage ContainerContext to adjust OCI spec
 
 ##### Exsiting Pod
 We leverage reconciler to reconcile exiting pods and to ensure eventual consistency of pod's LLC/MBA.
@@ -456,7 +473,7 @@ In this part, some metrics are evaluated for performance after Resctrl Hook Plug
 - Rely on NRI which Koordinator support from v1.3.0
 ## Alternatives
 
-Resctrl QoSManager Plugin is an asynchronize plugin which may not reconcile RDT resource in real time and need to iterate all task ids in pod/container periodically.
+Resctrl QoSManager Plugin is an asynchronize plugin which may not reconcile LLC/MBA resource in real time and need to iterate all task ids in pod/container periodically.
 
 ## Upgrade Strategy