Split Dynamic Resource Allocation into a Resource Management section

content/en/docs/concepts/resource-management/_index.md

@@ -0,0 +1,16 @@
+---
+title: Resource Management
+content_type: concept
+weight: 97
+description: >
+  How Kubernetes represents, requests, allocates, and constrains the resources
+  that workloads consume.
+---
+
+<!-- overview -->
+
+This section covers how Kubernetes represents, requests, allocates, and
+constrains the resources that workloads consume, including specialized hardware
+devices.
+
+<!-- body -->

content/en/docs/concepts/resource-management/dynamic-resource-allocation/_index.md

@@ -0,0 +1,99 @@
+---
+reviewers:
+- klueska
+- pohly
+title: Dynamic Resource Allocation
+content_type: concept
+weight: 20
+aliases:
+- /docs/concepts/scheduling-eviction/dynamic-resource-allocation/
+---
+
+<!-- overview -->
+
+{{< feature-state feature_gate_name="DynamicResourceAllocation" >}}
+
+This section introduces _dynamic resource allocation (DRA)_ in Kubernetes.
+
+<!-- body -->
+
+## About DRA {#about-dra}
+
+{{< glossary_definition prepend="DRA is" term_id="dra" length="all" >}}
+
+Allocating resources with DRA is a similar experience to
+[dynamic volume provisioning](/docs/concepts/storage/dynamic-provisioning/),
+in which you use PersistentVolumeClaims to claim storage capacity from storage classes
+and request the claimed capacity in your Pods.
+
+### Benefits of DRA {#dra-benefits}
+
+DRA provides a flexible way to categorize, request, and use devices in your cluster.
+Using DRA provides benefits like the following:
+
+* **Flexible device filtering**: use common expression language (CEL) to perform
+  fine-grained filtering for specific device attributes.
+* **Device sharing**: share the same resource with multiple containers or Pods
+  by referencing the corresponding resource claim.
+* **Centralized device categorization**: device drivers and cluster admins can
+  use device classes to provide app operators with hardware categories that are
+  optimized for various use cases. For example, you can create a cost-optimized
+  device class for general-purpose workloads, and a high-performance device
+  class for critical jobs.
+* **Simplified Pod requests**: with DRA, app operators don't need to specify
+  device quantities in Pod resource requests. Instead, the Pod references a
+  resource claim, and the device configuration in that claim applies to the Pod.
+
+These benefits provide significant improvements in the device allocation
+workflow when compared to
+[device plugins](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/),
+which require per-container device requests, don't support device sharing, and
+don't support expression-based device filtering.
+
+### Types of DRA users {#dra-user-types}
+
+The workflow of using DRA to allocate devices involves the following types of users:
+
+* **Device owner**: responsible for devices. Device owners might be commercial
+  vendors, the cluster operator, or another entity. To use DRA, devices must
+  have DRA-compatible drivers that do the following:
+
+  * Create ResourceSlices that provide Kubernetes with information about
+    nodes and resources.
+  * Update ResourceSlices when resource capacity in the cluster changes.
+  * Optionally, create DeviceClasses that workload operators can use to
+    claim devices.
+
+* **Cluster admin**: responsible for configuring clusters and nodes,
+  attaching devices, installing drivers, and similar tasks. To use DRA,
+  cluster admins do the following:
+
+  * Attach devices to nodes.
+  * Install device drivers that support DRA.
+  * Optionally, create DeviceClasses that workload operators can use to claim devices.
+
+* **Workload operator**: responsible for deploying and managing workloads in the
+  cluster. To use DRA to allocate devices to Pods, workload operators do the following:
+
+  * Create ResourceClaims or ResourceClaimTemplates to request specific
+    configurations within DeviceClasses.
+  * Deploy workloads that use specific ResourceClaims or ResourceClaimTemplates.
+
+## Limitations
+
+* The Kubernetes scheduler doesn't support
+  [preemption](/docs/concepts/scheduling-eviction/pod-priority-preemption/) for
+  DRA resources. This means that an existing Pod that's running on a node and is
+  using DRA resources can't be preempted by a higher-priority Pod that also needs
+  DRA resources. The high-priority Pod will remain in a pending state until the device
+  becomes available, which happens when the conflicting Pod terminates or is
+  manually deleted.
+
+## {{% heading "whatsnext" %}}
+
+- [Set Up DRA in a Cluster](/docs/tasks/configure-pod-container/assign-resources/set-up-dra-cluster/)
+- [Allocate devices to workloads using DRA](/docs/tasks/configure-pod-container/assign-resources/allocate-devices-dra/)
+- [Access DRA device metadata](/docs/tasks/configure-pod-container/assign-resources/access-dra-device-metadata/)
+- For more information on the design, see the
+  [Dynamic Resource Allocation with Structured Parameters](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/4381-dra-structured-parameters)
+  KEP.

content/en/docs/concepts/resource-management/dynamic-resource-allocation/device-taints.md

@@ -0,0 +1,192 @@
+---
+reviewers:
+- klueska
+- pohly
+title: Device Taints and Tolerations
+content_type: concept
+weight: 50
+api_metadata:
+- apiVersion: "resource.k8s.io/v1alpha3"
+  kind: "DeviceTaintRule"
+- apiVersion: "resource.k8s.io/v1beta2"
+  kind: "DeviceTaintRule"
+---
+
+<!-- overview -->
+
+This page describes device taints and tolerations in DRA, which let drivers and
+admins keep Pods off specific devices, or evict Pods already using them.
+
+<!-- body -->
+
+## Device taints and tolerations {#device-taints-and-tolerations}
+
+{{< feature-state feature_gate_name="DRADeviceTaints" >}}
+
+Device taints are similar to node taints: a taint has a string key, a string value, and an effect.
+The effect is applied to the ResourceClaim which is using a tainted device and to all Pods referencing that ResourceClaim.
+The "NoSchedule" effect prevents scheduling those Pods.
+Tainted devices are ignored when trying to allocate a ResourceClaim because using them would prevent scheduling of Pods.
+
+The "NoExecute" effect implies "NoSchedule" and in addition causes eviction of all Pods
+which have been scheduled already.
+This eviction is implemented in the device taint eviction controller in kube-controller-manager by deleting affected Pods.
+
+The "None" effect is ignored by the scheduler and eviction controller.
+DRA drivers can use it to communicate exceptions to admins or other controllers,
+like for example degraded health of a device. Admins can also use it to
+do dry-runs of pod eviction in DeviceTaintRules (more on that below).
+
+ResourceClaims can tolerate taints. If a taint is tolerated, its effect does not apply.
+An empty toleration matches all taints. A toleration can be limited to certain effects
+and/or match certain key/value pairs.
+A toleration can check that a certain key exists, regardless which value it has, or it can check
+for specific values of a key.
+For more information on this matching see the
+[node taint concepts](/docs/concepts/scheduling-eviction/taint-and-toleration#concepts).
+
+Eviction can be delayed by tolerating a taint for a certain duration.
+That delay starts at the time when a taint gets added to a device, which is recorded in a field of the taint.
+
+Taints apply as described above also to ResourceClaims allocating "all" devices on a node.
+All devices must be untainted or all of their taints must be tolerated.
+Allocating a device with admin access (described [above](#admin-access))
+is not exempt either. An admin using that mode must explicitly tolerate all taints
+to access tainted devices.
+
+Device taints and tolerations is controlled by the
+[`DRADeviceTaints` feature gate](/docs/reference/command-line-tools-reference/feature-gates/#DRADeviceTaints)
+in the `kube-apiserver`, `kube-controller-manager`, and `kube-scheduler`.
+To use DeviceTaintRules, the `resource.k8s.io/v1beta2` API version must be
+enabled together with the [`DRADeviceTaintRules` feature gate](/docs/reference/command-line-tools-reference/feature-gates/#DRADeviceTaintRules).
+In contrast to `DRADeviceTaints`, `DRADeviceTaintRules` is off by default because of this dependency
+on the beta API group, which has to be off by default.
+
+You can add taints to devices in the following ways, by using the DeviceTaintRule API kind.
+
+### Taints set by the driver
+
+A DRA driver can add taints to the device information that it publishes in ResourceSlices.
+Consult the documentation of a DRA driver to learn whether the driver uses taints and what their keys and values are.
+
+### Taints set by an admin
+
+{{< feature-state feature_gate_name="DRADeviceTaintRules" >}}
+
+An admin or a control plane component can taint devices without having to tell
+the DRA driver to include taints in its device information in ResourceSlices.
+They do that by creating DeviceTaintRules.
+Each DeviceTaintRule adds one taint to devices which match the device selector.
+Without such a selector, no devices are tainted.
+This makes it harder to accidentally evict all pods using ResourceClaims when leaving out the selector by mistake.
+
+Devices can be selected by giving the name of a DeviceClass, driver, pool, and/or device.
+The DeviceClass selects all devices that are selected by the selectors in that DeviceClass.
+With just the driver name, an admin can taint all devices managed by that driver,
+for example while doing some kind of maintenance of that driver across the entire cluster.
+Adding a pool name can limit the taint to a single node, if the driver manages node-local devices.
+
+Finally, adding the device name can select one specific device.
+The device name and pool name can also be used alone, if desired.
+For example, drivers for node-local devices are encouraged to use the node name as their pool name.
+Then tainting with that pool name automatically taints all devices on a node.
+
+Drivers might use stable names like "gpu-0" that hide which specific device is currently assigned to that name.
+To support tainting a specific hardware instance, CEL selectors can be used in a DeviceTaintRule
+to match a vendor-specific unique ID attribute, if the driver supports one for its hardware.
+
+The taint applies as long as the DeviceTaintRule exists.
+It can be modified and and removed at any time.
+Here is one example of a DeviceTaintRule for a fictional DRA driver:
+
+```yaml
+apiVersion: resource.k8s.io/v1beta2
+kind: DeviceTaintRule
+metadata:
+  name: example
+spec:
+  # The entire hardware installation for this
+  # particular driver is broken.
+  # Evict all pods and don't schedule new ones.
+  deviceSelector:
+    driver: dra.example.com
+  taint:
+    key: dra.example.com/unhealthy
+    value: Broken
+    effect: NoExecute
+```
+
+The kube-apiserver automatically tracks when this taint was created by setting the
+`timeAdded` field in the `spec`. The toleration period starts at that time
+stamp. During updates which change the effect (see simulated eviction flow
+below), the kube-apiserver automatically updates the time stamp. Users can control
+the time stamp explicitly by setting the field when creating a DeviceTaintRule and
+by changing it to some different value when updating.
+
+The status contains a condition added by the eviction controller:
+
+```
+kubectl describe devicetaintrules
+```
+
+```
+Name:         example
+...
+Spec:
+  Device Selector:
+    Driver:  dra.example.com
+  Taint:
+    Effect:      NoExecute
+    Key:         dra.example.com/unhealthy
+    Time Added:  2025-11-05T18:15:37Z
+    Value:       Broken
+Status:
+  Conditions:
+    Last Transition Time:  2025-11-05T18:15:37Z
+    Message:               1 pod evicted since starting the controller.
+    Observed Generation:   1
+    Reason:                Completed
+    Status:                False
+    Type:                  EvictionInProgress
+Events:                    <none>
+```
+
+Pods get evicted by deleting them. Usually this happens very quickly,
+except when a toleration for the taint delays it for a certain period or
+when there are very many pods which need to be evicted. When it takes
+longer, the message provides information about the current status:
+
+    2 pods need to be evicted in 2 different namespaces. 1 pod evicted since starting the controller.
+
+The condition can be used to check whether an eviction is currently active:
+
+    kubectl wait --for=condition=EvictionInProgress=false DeviceTaintRule/example
+
+Beware of the potential race between scheduler and controller observing the new
+taint at different times, which can lead to pods still being scheduled at a
+time when the controller thinks that there are none which need to be evicted
+and thus sets this condition to `False`. In practice, this race is made very
+unlikely by updating the status only after an intentional delay of a few
+seconds.
+
+For `effect: None`, the message provides information about the number of
+affected devices, how many of those are allocated, and how many pods would be
+evicted if the effect was `NoExecute`. This can be used to do a dry-run before
+actually triggering eviction:
+
+- Create a DeviceTaintRule with the desired selectors and `effect: None`.
+
+- Review the message:
+
+  ```
+  3 published devices selected. 1 allocated device selected.
+  1 pod would be evicted in 1 namespace if the effect was NoExecute.
+  This information will not be updated again. Recreate the DeviceTaintRule to trigger an update.
+  ```
+
+  Published devices are those listed in ResourceSlices. Tainting them
+  prevents allocation for new pods. Only allocated devices cause
+  eviction of the pods using them.
+
+- Edit the DeviceTaintRule and change the effect into `NoExecute`.
+