Merge pull request #5316 from gauravkghildiyal/kep-4381-dra-standard-attributes

KEP-4381: Define standard device attributes

Author: k8s-ci-robot

keps/sig-node/4381-dra-structured-parameters/README.md

@@ -568,7 +568,7 @@ spec:
           version: 11.1.42
         powerSavingSupported:
           bool: true
-        dra.k8s.io/pciRoot: # a fictional standardized attribute, not actually part of this KEP
+        resource.kubernetes.io/pcieRoot:
           string: pci-root-0
       capacity:
         memory: 16Gi
@@ -578,10 +578,14 @@ Compared to labels, attributes have values of exactly one type. Quantities are d
 in the separate `capacity` map. As described later on, both sets can be used in CEL expressions to select a
 specific resource for allocation on a node.
 
-To avoid any future conflicts, we reserve any attributes with the ".k8s.io/" domain prefix
-for future use and standardization by Kubernetes. This could be used to describe
-topology across resources from different vendors, for example, but this is out-
-of-scope for now.
+We are reserving the `kubernetes.io/` domain (and subdomains) prefix for
+attributes and capacities for standardization by the Kubernetes project. This
+reservation allows us to define common attributes that can describe hardware
+characteristics across resources from different vendors. Currently, we are
+defining one such standard attribute: `resource.kubernetes.io/pcieRoot`. Details
+on its meaning and how it should be exposed by DRA drivers are available in the
+[API design section under ResourceSlice's](#resourceslice) QualifiedName
+definition.
 
 **Note:** If a driver needs to remove a device or change its attributes,
 then there is a risk that a claim gets allocated based on the old
@@ -594,6 +598,19 @@ would allow us to delete the pod and trying again with a new one, but is not don
 at the moment because admission checks cannot be retried if a check finds
 a transient problem.
 
+**Note:** The immediate motivation for standardizing attributes largely stems
+from the current behavior of the `MatchAttribute` constraint, which relies on
+exact value matching. While this KEP provides a solution for many cross-driver
+alignment needs, a more flexible long-term solution is envisioned with
+[KEP-5254: DRA support for MatchExpression
+constraints](https://github.com/kubernetes/enhancements/issues/5254) (a
+work-in-progress). That proposal aims to introduce a `MatchExpression`
+constraint, allowing devices to be evaluated against CEL expressions, which will
+enable more complex and dynamic selection criteria. However, solving this
+critical alignment problem today is essential for latency-sensitive workloads.
+Standardizing attributes helps achieve this without introducing any conflicts
+with the future capabilities of KEP-5254.
+
 ### Using structured parameters
 
 A ResourceClaim is a request to allocate one or more devices. Each request in a
@@ -1212,6 +1229,23 @@ const ResourceSliceMaxAttributesAndCapacitiesPerDevice = 32
 // domain prefix are assumed to be part of the driver's domain. Attributes
 // or capacities defined by 3rd parties must include the domain prefix.
 //
+// The Kubernetes project reserves the "kubernetes.io/" domain prefix for
+// standardizing attributes and capacities. DRA drivers **SHOULD** use these
+// standardized names if they define a characteristic of a device that matches
+// the intent of a standard attribute (or capacity) name. This ensures
+// consistency and interoperability across different drivers when conveying the
+// same idea.
+//
+// Currently, the following standard attributes have been defined:
+//
+//  1. `resource.kubernetes.io/pcieRoot`: A string value in the format
+//     `pci<domain>:<bus>`, referring to a PCIe (Peripheral Component
+//     Interconnect Express) Root Complex. This attribute can be used to
+//     identify devices that share the same PCIe Root Complex. DRA drivers MAY
+//     determine this value by inspecting the hierarchical path of the device's
+//     entry in sysfs (e.g., `/sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0`),
+//     where the `pci<domain>:<bus>` segment at the beginning of the real path
+//     identifies the Root Complex (e.g., `pci0000:00`).
 //
 // The maximum length for the DNS subdomain is 63 characters (same as
 // for driver names) and the maximum length of the C identifier