diff --git a/keps/sig-node/4381-dra-structured-parameters/README.md b/keps/sig-node/4381-dra-structured-parameters/README.md index a0ba5ccefcc..c42a1a4020c 100644 --- a/keps/sig-node/4381-dra-structured-parameters/README.md +++ b/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:`, 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:` 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