Merge pull request #51731 from Jpsassine/dra-health-docs

docs(DRA): Document device health monitoring in PodStatus

Author: k8s-ci-robot

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

@@ -310,6 +310,7 @@ following methods:
 
 * [kubelet device metrics](#monitoring-resources)
 * [ResourceClaim status](#resourceclaim-device-status)
+* [Device health monitoring](#device-health-monitoring)
 
 ### kubelet device metrics {#monitoring-resources}
 
@@ -343,6 +344,19 @@ set.
 For details about the `status.devices` field, see the
 {{< api-reference page="workload-resources/resource-claim-v1beta1" anchor="ResourceClaimStatus" text="ResourceClaim" >}} API reference.
 
+### Device Health Monitoring {#device-health-monitoring}
+
+{{< feature-state feature_gate_name="ResourceHealthStatus" >}}
+
+As an alpha feature, Kubernetes provides a mechanism for monitoring and reporting the health of dynamically allocated infrastructure resources.
+For stateful applications running on specialized hardware, it is critical to know when a device has failed or become unhealthy. It is also helpful to find out if the device recovers.
+
+To enable this functionality, the `ResourceHealthStatus` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/resource-health-status/) must be enabled, and the DRA driver must implement the `DRAResourceHealth` gRPC service.
+
+When a DRA driver detects that an allocated device has become unhealthy, it reports this status back to the kubelet. This health information is then exposed directly in the Pod's status. The kubelet populates the `allocatedResourcesStatus` field in the status of each container, detailing the health of each device assigned to that container.
+
+This provides crucial visibility for users and controllers to react to hardware failures. For a Pod that is failing, you can inspect this status to determine if the failure was related to an unhealthy device.
+
 ## Pre-scheduled Pods
 
 When you - or another API client - create a Pod with `spec.nodeName` already set, the scheduler gets bypassed.

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

@@ -13,4 +13,5 @@ stages:
 Enable the `allocatedResourcesStatus` field within the `.status` for a Pod. The field
 reports additional details for each container in the Pod,
 with the health information for each device assigned to the Pod.
-See [Device plugin and unhealthy devices](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#device-plugin-and-unhealthy-devices) for more details.
+
+This feature applies to devices managed by both [Device Plugins](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#device-plugin-and-unhealthy-devices) and [Dynamic Resource Allocation](/docs/concepts/scheduling-eviction/dynamic-resource-allocation/#device-health-monitoring). See [Device plugin and unhealthy devices](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#device-plugin-and-unhealthy-devices) for more details.