doc: document exposing and observing balloons in NRT

Signed-off-by: Antti Kervinen <[email protected]>

docs/resource-policy/policy/balloons.md

@@ -8,7 +8,10 @@ can be dynamically inflated and deflated, that is CPUs added and
 removed, based on the CPU resource requests of containers running in
 the balloon. Balloons can be static or dynamically created and
 destroyed. CPUs in balloons can be configured, for example, by setting
-min and max frequencies on CPU cores and uncore.
+min and max frequencies on CPU cores and uncore. Balloons in
+Kubernetes cluster, including CPU and memory affinities of their
+containers, can be exposed and observed through noderesourcetopologies
+custom resources.
 
 ## How It Works
 
@@ -124,6 +127,14 @@ Balloons policy parameters:
   value set here is the default for all balloon types, but it can be
   overridden with the balloon type specific setting with the same
   name.
+- `showContainersInNrt` controls whether containers in balloons are
+  exposed as part of NodeResourceTopology. If `true`,
+  noderesourcetopologies.topology.node.k8s.io custom resources provide
+  visibility to CPU and memory affinity of containers assigned into
+  balloons. The default is `false`. Use balloon-type option with the
+  same name to override the policy-level default. Note that this has
+  no effect unless `agent:NodeResourceTopology` enables node resource
+  topology exposure in general.
 - `balloonTypes` is a list of balloon type definitions. The order of
   the types is significant in two cases.
 
@@ -271,6 +282,13 @@ Balloons policy parameters:
      and assigned containers are readable through `/metrics` from the
      httpEndpoint.
   - `reportPeriod`: `/metrics` aggregation interval for polled metrics.
+- `agent`: controls communicating with the Kubernetes node agent and
+  the API server.
+  - `nodeResourceTopology`: if `true`, expose balloons as node
+    resource topology zones in noderesourcetopologies custom
+    resources. Moreover, showing containers assigned to balloons and
+    their CPU/memory affinities can be enabled with
+    `showContainersInNrt`. The default is `false`.
 
 ### Example
 
@@ -285,6 +303,11 @@ metadata:
   name: default
   namespace: kube-system
 spec:
+  # Expose balloons as node resource topology zones in
+  # noderesourcestopologies custom resources.
+  agent:
+    nodeResourceTopology: true
+
   reservedResources:
     cpu: 1000m
   pinCPU: true
@@ -297,6 +320,7 @@ spec:
       cpuClass: dynamic
       namespaces:
         - "*"
+      showContainersInNrt: true
   control:
     cpu:
       classes: