[KEP-5075] DRAConsumableCapacity documentation

Signed-off-by: Sunyanan Choochotkaew <sunyanan.choochotkaew1@ibm.com>

Author: sunya-ch

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

@@ -530,6 +530,90 @@ Partitionable devices is an *alpha feature* and only enabled when the
 [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
 is enabled in the kube-apiserver and kube-scheduler.
 
+## Consumable capacity
+
+{{< feature-state feature_gate_name="DRAConsumableCapacity" >}}
+
+A device with the property `allowMultipleAllocations` can be allocated or shared
+among multiple independent ResourceClaim's requests.
+
+For a device sharing purpose, consumable capacity refers to the device capacity that,
+the driver can manage and dynamically allocate a portion of it to a Pod,
+based on the amount requested in a ResourceClaim and its `requestPolicy`.
+
+Here is an example of a network device which allows multiple allocations and contains
+a consumable bandwidth capacity.
+
+```yaml
+kind: ResourceSlice
+apiVersion: resource.k8s.io/v1beta2
+metadata:
+  name: resourceslice
+spec:
+  nodeName: worker-1
+  pool:
+    name: pool
+    generation: 1
+    resourceSliceCount: 1
+  driver: dra.example.com
+  devices:
+  - name: eth1
+    basic:
+      allowMultipleAllocations: true
+      attributes:
+        name:
+          string: "eth1"
+      capacity:
+        bandwidth:
+          requestPolicy:
+            default: "1M"
+            validRange:
+              min: "1M"
+              step: "8"
+          value: "10G"
+```
+
+The property of `allowMultipleAllocations` can be used in CEL
+and the consumable capacity can be requested as shown in the below example.
+
+```yaml
+apiVersion: resource.k8s.io/v1beta2
+kind: ResourceClaimTemplate
+metadata:
+  name: bandwidth-claim-template
+spec:
+  spec:
+    devices:
+      requests:
+      - name: req-0
+        exactly:
+        - name:
+          deviceClassName: resource.example.com
+          selectors:
+          - cel:
+              expression: |-
+                device.allowMultipleAllocations == true
+          capacity:
+            requests:
+              bandwidth: 1G
+```
+
+The allocation result will include the consumed capacity and the identifier of the share.
+
+```yaml
+apiVersion: resource.k8s.io/v1beta2
+kind: ResourceClaim
+...
+status:
+  allocation:
+    devices:
+      results:
+      - consumedCapacity:
+          bandwidth: 1G
+        device: eth1
+        shareID: "a671734a-e8e5-11e4-8fde-42010af09327"
+```
+
 ### Device taints and tolerations {#device-taints-and-tolerations}
 
 {{< feature-state feature_gate_name="DRADeviceTaints" >}}

content/en/docs/reference/command-line-tools-reference/feature-gates/DRAConsumableCapacity.md

@@ -0,0 +1,15 @@
+---
+title: DRAConsumableCapacity
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.34"
+---
+Enables device sharing across multiple ResourceClaims or requests.
+
+Additionally, if a device supports sharing, its resource (capacity) can be managed through a defined sharing policy.