Merge pull request #51091 from shannonxtreme/dra-docs-improve

Add foundational docs improvements for DRA

Author: k8s-ci-robot

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

@@ -0,0 +1,24 @@
+---
+title: Common Expression Language
+id: cel
+date: 2025-06-04
+full_link: https://cel.dev
+short_description: >
+  An expression language that's designed to be safe for executing user code.
+tags:
+- extension
+- fundamental
+aka:
+- CEL
+---
+ A general-purpose expression language that's designed to be fast, portable, and
+safe to execute.
+
+<!--more-->
+
+In Kubernetes, CEL can be used to run queries and perform fine-grained
+filtering. For example, you can use CEL expressions with
+[dynamic admission control](/docs/reference/access-authn-authz/extensible-admission-controllers/)
+to filter for specific fields in requests, and with
+[dynamic resource allocation (DRA)](/docs/concepts/scheduling-eviction/dynamic-resource-allocation)
+to select resources based on specific attributes.

content/en/docs/reference/glossary/cel.md

@@ -0,0 +1,23 @@
+---
+title: Device
+id: device
+date: 2025-05-13
+short_description: >
+  Any resource that's directly or indirectly attached your cluster's nodes, like
+  GPUs or circuit boards.
+
+tags:
+- extension
+- fundamental
+---
+ One or more
+{{< glossary_tooltip text="infrastructure resources" term_id="infrastructure-resource" >}}
+that are directly or indirectly attached to your
+{{< glossary_tooltip text="nodes" term_id="node" >}}.
+
+<!--more-->
+
+Devices might be commercial products like GPUs, or custom hardware like
+[ASIC boards](https://en.wikipedia.org/wiki/Application-specific_integrated_circuit).
+Attached devices usually require device drivers that let Kubernetes
+{{< glossary_tooltip text="Pods" term_id="pod" >}} access the devices.

content/en/docs/reference/glossary/device.md

@@ -0,0 +1,23 @@
+---
+title: DeviceClass
+id: deviceclass
+date: 2025-05-26
+full_link: /docs/concepts/scheduling-eviction/dynamic-resource-allocation/#deviceclass
+short_description: >
+  A category of devices in the cluster. Users can claim specific
+  devices in a DeviceClass.
+tags:
+- extension
+---
+ A category of {{< glossary_tooltip text="devices" term_id="device" >}} in the
+ cluster that can be used with dynamic resource allocation (DRA).
+
+<!--more-->
+
+Administrators or device owners use DeviceClasses to define a set of devices
+that can be claimed and used in workloads. Devices are claimed by creating
+{{< glossary_tooltip text="ResourceClaims" term_id="resourceclaim" >}}
+that filter for specific device parameters in a DeviceClass.
+
+For more information, see
+[Dynamic Resource Allocation](/docs/concepts/scheduling-eviction/dynamic-resource-allocation/#deviceclass)

content/en/docs/reference/glossary/deviceclass.md

@@ -0,0 +1,25 @@
+---
+title: Dynamic Resource Allocation
+id: dra
+date: 2025-05-13
+full_link: /docs/concepts/scheduling-eviction/dynamic-resource-allocation/
+short_description: >
+  A Kubernetes feature for requesting and sharing resources, like hardware
+  accelerators, among Pods.
+
+aka:
+- DRA
+tags:
+- extension
+---
+ A Kubernetes feature that lets you request and share resources among Pods.
+These resources are often attached
+{{< glossary_tooltip text="devices" term_id="device" >}} like hardware
+accelerators.
+
+<!--more-->
+
+With DRA, device drivers and cluster admins define device _classes_ that are
+available to _claim_ in workloads. Kubernetes allocates matching devices to
+specific claims and places the corresponding Pods on nodes that can access the
+allocated devices.

content/en/docs/reference/glossary/dra.md

@@ -0,0 +1,23 @@
+---
+title: ResourceClaim
+id: resourceclaim
+date: 2025-05-26
+full_link: /docs/concepts/scheduling-eviction/dynamic-resource-allocation/#resourceclaims-templates
+short_description: >
+  Describes the resources that a workload needs, such as devices. ResourceClaims
+  can request devices from DeviceClasses.
+
+tags:
+- workload
+---
+ Describes the resources that a workload needs, such as
+{{< glossary_tooltip text="devices" term_id="device" >}}. ResourceClaims are
+used in
+[dynamic resource allocation (DRA)](/docs/concepts/scheduling-eviction/dynamic-resource-allocation/)
+to provide Pods with access to a specific resource.
+
+<!--more-->
+
+ResourceClaims can be created by workload operators or generated by Kubernetes
+based on a
+{{< glossary_tooltip text="ResourceClaimTemplate" term_id="resourceclaimtemplate" >}}.

content/en/docs/reference/glossary/resourceclaim.md

@@ -0,0 +1,24 @@
+---
+title: ResourceClaimTemplate
+id: resourceclaimtemplate
+date: 2025-05-26
+full_link: /docs/concepts/scheduling-eviction/dynamic-resource-allocation/#resourceclaims-templates
+short_description: >
+  Defines a template for Kubernetes to create ResourceClaims. Used to provide
+  per-Pod access to separate, similar resources.
+
+tags:
+- workload
+---
+ Defines a template that Kubernetes uses to create
+{{< glossary_tooltip text="ResourceClaims" term_id="resourceclaim" >}}. 
+ResourceClaimTemplates are used in
+[dynamic resource allocation (DRA)](/docs/concepts/scheduling-eviction/dynamic-resource-allocation/)
+to provide _per-Pod access to separate, similar resources_.
+
+<!--more-->
+
+When a ResourceClaimTemplate is referenced in a workload specification,
+Kubernetes automatically creates ResourceClaim objects based on the template.
+Each ResourceClaim is bound to a specific Pod. When the Pod terminates,
+Kubernetes deletes the corresponding ResourceClaim. 

content/en/docs/reference/glossary/resourceclaimtemplate.md

@@ -0,0 +1,24 @@
+---
+title: ResourceSlice
+id: resourceslice
+date: 2025-05-26
+full_link: /docs/reference/kubernetes-api/workload-resources/resource-slice-v1beta1/
+short_description: >
+  Represents one or more infrastructure resources, like devices, in a pool of
+  similar resources.
+
+tags:
+- workload
+---
+ Represents one or more infrastructure resources, such as
+{{< glossary_tooltip text="devices" term_id="device" >}}, that are attached to
+nodes. Drivers create and manage ResourceSlices in the cluster. ResourceSlices
+are used for
+[dynamic resource allocation (DRA)](/docs/concepts/scheduling-eviction/dynamic-resource-allocation/).
+
+<!--more-->
+
+When a {{< glossary_tooltip text="ResourceClaim" term_id="resourceclaim" >}} is
+created, Kubernetes uses ResourceSlices to find nodes that have access to
+resources that can satisfy the claim. Kubernetes allocates resources to the
+ResourceClaim and schedules the Pod onto a node that can access the resources.

content/en/docs/reference/glossary/resourceslice.md

@@ -0,0 +1,6 @@
+---
+title: "Assign Devices to Pods and Containers"
+description: Assign infrastructure resources to your Kubernetes workloads.
+weight: 30
+---
+

content/en/docs/tasks/configure-pod-container/assign-resources/_index.md

@@ -0,0 +1,186 @@
+---
+title: Allocate Devices to Workloads with DRA
+content_type: task
+min-kubernetes-server-version: v1.32
+weight: 20
+---
+{{< feature-state feature_gate_name="DynamicResourceAllocation" >}}
+
+<!-- overview -->
+
+This page shows you how to allocate devices to your Pods by using
+_dynamic resource allocation (DRA)_. These instructions are for workload
+operators. Before reading this page, familiarize yourself with how DRA works and
+with DRA terminology like
+{{< glossary_tooltip text="ResourceClaims" term_id="resourceclaim" >}} and
+{{< glossary_tooltip text="ResourceClaimTemplates" term_id="resourceclaimtemplate" >}}.
+For more information, see
+[Dynamic Resource Allocation (DRA)](/docs/concepts/scheduling-eviction/dynamic-resource-allocation/).
+
+<!-- body -->
+
+## About device allocation with DRA {#about-device-allocation-dra}
+
+As a workload operator, you can _claim_ devices for your workloads by creating
+ResourceClaims or ResourceClaimTemplates. When you deploy your workload,
+Kubernetes and the device drivers find available devices, allocate them to your
+Pods, and place the Pods on nodes that can access those devices.
+
+<!-- prerequisites -->
+
+## {{% heading "prerequisites" %}}
+
+{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
+
+* Ensure that your cluster admin has set up DRA, attached devices, and installed
+  drivers. For more information, see
+  [Set Up DRA in a Cluster](/docs/tasks/configure-pod-container/assign-resources/set-up-dra-cluster).
+
+<!-- steps -->
+
+## Identify devices to claim {#identify-devices}
+
+Your cluster administrator or the device drivers create
+_{{< glossary_tooltip term_id="deviceclass" text="DeviceClasses" >}}_ that
+define categories of devices. You can claim devices by using
+{{< glossary_tooltip term_id="cel" >}} to filter for specific device properties.
+
+Get a list of DeviceClasses in the cluster:
+
+```shell
+kubectl get deviceclasses
+```
+The output is similar to the following:
+
+```
+NAME                 AGE
+driver.example.com   16m
+```
+If you get a permission error, you might not have access to get DeviceClasses.
+Check with your cluster administrator or with the driver provider for available
+device properties.
+
+## Claim resources {#claim-resources}
+
+You can request resources from a DeviceClass by using 
+{{< glossary_tooltip text="ResourceClaims" term_id="resourceclaim" >}}. To
+create a ResourceClaim, do one of the following:
+
+* Manually create a ResourceClaim if you want multiple Pods to share access to
+  the same devices, or if you want a claim to exist beyond the lifetime of a
+  Pod.
+* Use a
+  {{< glossary_tooltip text="ResourceClaimTemplate" term_id="resourceclaimtemplate" >}}
+  to let Kubernetes generate and manage per-Pod ResourceClaims. Create a
+  ResourceClaimTemplate if you want every Pod to have access to separate devices
+  that have similar configurations. For example, you might want simultaneous
+  access to devices for Pods in a Job that uses
+  [parallel execution](/docs/concepts/workloads/controllers/job/#parallel-jobs).
+
+If you directly reference a specific ResourceClaim in a Pod, that ResourceClaim
+must already exist in the cluster. If a referenced ResourceClaim doesn't exist,
+the Pod remains in a pending state until the ResourceClaim is created. You can
+reference an auto-generated ResourceClaim in a Pod, but this isn't recommended
+because auto-generated ResourceClaims are bound to the lifetime of the Pod that
+triggered the generation.
+
+To create a workload that claims resources, select one of the following options:
+
+{{< tabs name="claim-resources" >}}
+{{% tab name="ResourceClaimTemplate" %}}
+
+Review the following example manifest: 
+
+{{% code_sample file="dra/resourceclaimtemplate.yaml" %}}
+
+This manifest creates a ResourceClaimTemplate that requests devices in the
+`example-device-class` DeviceClass that match both of the following parameters:
+
+  * Devices that have a `driver.example.com/type` attribute with a value of
+    `gpu`.
+  * Devices that have `64Gi` of capacity.
+
+To create the ResourceClaimTemplate, run the following command:
+
+```shell
+kubectl apply -f https://k8s.io/examples/dra/resourceclaimtemplate.yaml
+```
+
+{{% /tab %}}
+{{% tab name="ResourceClaim" %}}
+
+Review the following example manifest:
+
+{{% code_sample file="dra/resourceclaim.yaml" %}}
+
+This manifest creates ResourceClaim that requests devices in the
+`example-device-class` DeviceClass that match both of the following parameters:
+
+  * Devices that have a `driver.example.com/type` attribute with a value of
+    `gpu`.
+  * Devices that have `64Gi` of capacity.
+
+To create the ResourceClaim, run the following command:
+
+```shell
+kubectl apply -f https://k8s.io/examples/dra/resourceclaim.yaml
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+## Request devices in workloads using DRA {#request-devices-workloads}
+
+To request device allocation, specify a ResourceClaim or a ResourceClaimTemplate
+in the `resourceClaims` field of the Pod specification. Then, request a specific
+claim by name in the `resources.claims` field of a container in that Pod.
+You can specify multiple entries in the `resourceClaims` field and use specific
+claims in different containers.
+
+1. Review the following example Job:
+
+   {{% code_sample file="dra/dra-example-job.yaml" %}}
+
+   Each Pod in this Job has the following properties:
+   
+   * Makes a ResourceClaimTemplate named `separate-gpu-claim` and a
+     ResourceClaim named `shared-gpu-claim` available to containers.
+   * Runs the following containers:
+       * `container0` requests the devices from the `separate-gpu-claim` 
+         ResourceClaimTemplate. 
+       * `container1` and `container2` share access to the devices from the
+         `shared-gpu-claim` ResourceClaim.
+
+1. Create the Job: 
+
+   ```shell
+   kubectl apply -f https://k8s.io/examples/dra/dra-example-job.yaml
+   ```
+
+## Clean up {#clean-up}
+
+To delete the Kubernetes objects that you created in this task, follow these
+steps:
+
+1.  Delete the example Job:
+
+    ```shell
+    kubectl delete -f https://k8s.io/examples/dra/dra-example-job.yaml
+    ```
+
+1.  To delete your resource claims, run one of the following commands:
+
+    * Delete the ResourceClaimTemplate:
+
+      ```shell
+      kubectl delete -f https://k8s.io/examples/dra/resourceclaimtemplate.yaml
+      ```
+    * Delete the ResourceClaim:
+
+      ```shell
+      kubectl delete -f https://k8s.io/examples/dra/resourceclaim.yaml
+      ```
+
+## {{% heading "whatsnext" %}}
+
+* [Learn more about DRA](/docs/concepts/scheduling-eviction/dynamic-resource-allocation)