From 148469d7ff00960bc13bd331009eec1db50122de Mon Sep 17 00:00:00 2001
From: Patrick Ohly <patrick.ohly@intel.com>
Date: Tue, 27 Aug 2024 16:06:23 +0200
Subject: [PATCH] DRA API: update some comments

Mentioning potential future API extensions help with understanding why the API
is defined the way it is when reading just the types.go. Those stand-alone
comments appear neither in the Go doc nor OpenAPI.

This corresponds to https://github.com/kubernetes/enhancements/pull/4808.
---
 pkg/apis/resource/types.go                       | 16 ++++++++++++++++
 .../src/k8s.io/api/resource/v1alpha3/types.go    | 16 ++++++++++++++++
 .../kubelet/pkg/apis/dra/v1alpha4/api.pb.go      |  2 +-
 .../kubelet/pkg/apis/dra/v1alpha4/api.proto      |  2 +-
 4 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/pkg/apis/resource/types.go b/pkg/apis/resource/types.go
index 70e21b9e1ff..2c03a304fdf 100644
--- a/pkg/apis/resource/types.go
+++ b/pkg/apis/resource/types.go
@@ -362,6 +362,12 @@ type DeviceClaim struct {
 	// +optional
 	// +listType=atomic
 	Config []DeviceClaimConfiguration
+
+	// Potential future extension, ignored by older schedulers. This is
+	// fine because scoring allows users to define a preference, without
+	// making it a hard requirement.
+	//
+	// Score *SomeScoringStruct
 }
 
 const (
@@ -552,6 +558,16 @@ type DeviceConstraint struct {
 	// +optional
 	// +oneOf=ConstraintType
 	MatchAttribute *FullyQualifiedName
+
+	// Potential future extension, not part of the current design:
+	// A CEL expression which compares different devices and returns
+	// true if they match.
+	//
+	// Because it would be part of a one-of, old schedulers will not
+	// accidentally ignore this additional, for them unknown match
+	// criteria.
+	//
+	// MatchExpression string
 }
 
 // DeviceClaimConfiguration is used for configuration parameters in DeviceClaim.
diff --git a/staging/src/k8s.io/api/resource/v1alpha3/types.go b/staging/src/k8s.io/api/resource/v1alpha3/types.go
index 6c104e72189..e963fb63a2c 100644
--- a/staging/src/k8s.io/api/resource/v1alpha3/types.go
+++ b/staging/src/k8s.io/api/resource/v1alpha3/types.go
@@ -368,6 +368,12 @@ type DeviceClaim struct {
 	// +optional
 	// +listType=atomic
 	Config []DeviceClaimConfiguration `json:"config,omitempty" protobuf:"bytes,3,opt,name=config"`
+
+	// Potential future extension, ignored by older schedulers. This is
+	// fine because scoring allows users to define a preference, without
+	// making it a hard requirement.
+	//
+	// Score *SomeScoringStruct
 }
 
 const (
@@ -558,6 +564,16 @@ type DeviceConstraint struct {
 	// +optional
 	// +oneOf=ConstraintType
 	MatchAttribute *FullyQualifiedName `json:"matchAttribute,omitempty" protobuf:"bytes,2,opt,name=matchAttribute"`
+
+	// Potential future extension, not part of the current design:
+	// A CEL expression which compares different devices and returns
+	// true if they match.
+	//
+	// Because it would be part of a one-of, old schedulers will not
+	// accidentally ignore this additional, for them unknown match
+	// criteria.
+	//
+	// MatchExpression string
 }
 
 // DeviceClaimConfiguration is used for configuration parameters in DeviceClaim.
diff --git a/staging/src/k8s.io/kubelet/pkg/apis/dra/v1alpha4/api.pb.go b/staging/src/k8s.io/kubelet/pkg/apis/dra/v1alpha4/api.pb.go
index 581c708b732..23b2f5369cf 100644
--- a/staging/src/k8s.io/kubelet/pkg/apis/dra/v1alpha4/api.pb.go
+++ b/staging/src/k8s.io/kubelet/pkg/apis/dra/v1alpha4/api.pb.go
@@ -150,7 +150,7 @@ type NodePrepareResourceResponse struct {
 	// may have zero or more devices.
 	Devices []*Device `protobuf:"bytes,1,rep,name=devices,proto3" json:"devices,omitempty"`
 	// If non-empty, preparing the ResourceClaim failed.
-	// cdi_devices is ignored in that case.
+	// Devices are ignored in that case.
 	Error                string   `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"`
 	XXX_NoUnkeyedLiteral struct{} `json:"-"`
 	XXX_sizecache        int32    `json:"-"`
diff --git a/staging/src/k8s.io/kubelet/pkg/apis/dra/v1alpha4/api.proto b/staging/src/k8s.io/kubelet/pkg/apis/dra/v1alpha4/api.proto
index ddc33490252..cdf8fe0c721 100644
--- a/staging/src/k8s.io/kubelet/pkg/apis/dra/v1alpha4/api.proto
+++ b/staging/src/k8s.io/kubelet/pkg/apis/dra/v1alpha4/api.proto
@@ -67,7 +67,7 @@ message NodePrepareResourceResponse {
     // may have zero or more devices.
     repeated Device devices = 1;
     // If non-empty, preparing the ResourceClaim failed.
-    // cdi_devices is ignored in that case.
+    // Devices are ignored in that case.
     string error = 2;
 }