[KEP-4817] DRAResourceClaimDeviceStatus documentation

Signed-off-by: Lionel Jouin <[email protected]>

Author: LionelJouin

content/en/docs/concepts/scheduling-eviction/dynamic-resource-allocation.md

@@ -11,6 +11,10 @@ weight: 65
 
 {{< feature-state feature_gate_name="DynamicResourceAllocation" >}}
 
+Dynamic Resource Allocation with ResourceClaim device status:
+
+{{< feature-state feature_gate_name="DRAResourceClaimDeviceStatus" >}}
+
 Dynamic resource allocation is an API for requesting and sharing resources
 between pods and containers inside a pod. It is a generalization of the
 persistent volumes API for generic resources. Typically those resources
@@ -47,7 +51,11 @@ ResourceClaim
   for use by workloads. For example, if a workload needs an accelerator device
   with specific properties, this is how that request is expressed. The status
   stanza tracks whether this claim has been satisfied and what specific
-  resources have been allocated.
+  resources have been allocated. When the `DRAResourceClaimDeviceStatus` 
+  [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is
+  enabled, drivers can report driver-specific device status data for each allocated 
+  device in a resource claim. For example, IPs assigned to a network interface device
+  can be reported in the ResourceClaim status.
 
 ResourceClaimTemplate
 : Defines the spec and some metadata for creating
@@ -209,6 +217,10 @@ are enabled. For details on that, see the `--feature-gates` and `--runtime-confi
 [kube-apiserver parameters](/docs/reference/command-line-tools-reference/kube-apiserver/).
 kube-scheduler, kube-controller-manager and kubelet also need the feature gate.
 
+When a resource driver reports the status of the devices, then the
+`DRAResourceClaimDeviceStatus` feature gate has to be enabled in addition to
+`DynamicResourceAllocation`.
+
 A quick check whether a Kubernetes cluster supports the feature is to list
 DeviceClass objects with:
 
@@ -229,6 +241,11 @@ If not supported, this error is printed instead:
 error: the server doesn't have a resource type "deviceclasses"
 ```
 
+A ResourceClaim device status is supported when it is possible, from a DRA driver,
+to update an existing ResourceClaim where the `status.devices` field is set. When the
+`DRAResourceClaimDeviceStatus` feature is disabled, that field automatically
+gets cleared when storing the ResourceClaim.
+
 The default configuration of kube-scheduler enables the "DynamicResources"
 plugin if and only if the feature gate is enabled and when using
 the v1 configuration API. Custom configurations may have to be modified to

content/en/docs/reference/command-line-tools-reference/feature-gates/dra-resource-claim-device-status.md

@@ -0,0 +1,14 @@
+---
+title: DRAResourceClaimDeviceStatus
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.32"
+---
+Enables support the ResourceClaim.status.devices field and for setting this 
+status from DRA drivers.