DRA: Update types and defaults for Prioritized Alternatives in Device Requests

Author: mortent

pkg/apis/resource/types.go

@@ -388,16 +388,12 @@ const (
 // DeviceRequest is a request for devices required for a claim.
 // This is typically a request for a single resource like a device, but can
 // also ask for several identical devices.
-//
-// A DeviceClassName is currently required. Clients must check that it is
-// indeed set. It's absence indicates that something changed in a way that
-// is not supported by the client yet, in which case it must refuse to
-// handle the request.
 type DeviceRequest struct {
 	// Name can be used to reference this request in a pod.spec.containers[].resources.claims
 	// entry and in a constraint of the claim.
 	//
-	// Must be a DNS label.
+	// Must be a DNS label and unique among all DeviceRequests in a
+	// ResourceClaim.
 	//
 	// +required
 	Name string
@@ -406,15 +402,17 @@ type DeviceRequest struct {
 	// additional configuration and selectors to be inherited by this
 	// request.
 	//
-	// A class is required. Which classes are available depends on the cluster.
+	// A class is required if no subrequests are specified in the
+	// firstAvailable list. Which classes are available depends on the cluster.
 	//
 	// Administrators may use this to restrict which devices may get
 	// requested by only installing classes with selectors for permitted
 	// devices. If users are free to request anything without restrictions,
 	// then administrators can create an empty DeviceClass for users
 	// to reference.
 	//
-	// +required
+	// +optional
+	// +oneOf=deviceRequestType
 	DeviceClassName string
 
 	// Selectors define criteria which must be satisfied by a specific
@@ -468,10 +466,93 @@ type DeviceRequest struct {
 	// +optional
 	// +featureGate=DRAAdminAccess
 	AdminAccess *bool
+
+	// FirstAvailable contains subrequests, exactly one of which must be satisfied
+	// in order to satisfy this request. This field may only be set in the
+	// entries of DeviceClaim.Requests.
+	//
+	// +optional
+	// +oneOf=deviceRequestType
+	// +listType=atomic
+	// +featureGate=DRAPrioritizedList
+	FirstAvailable []DeviceSubRequest
+}
+
+// DeviceSubRequest describes a request for device provided in the
+// claim.spec.devices.requests[].firstAvailable array. Each
+// is typically a request for a single resource like a device, but can
+// also ask for several identical devices.
+//
+// DeviceSubRequest is similar to Request, but doesn't expose the AdminAccess
+// or FirstAvailable fields, as those can only be set on the top-level request.
+// AdminAccess is not supported for requests with a prioritized list, and
+// recursive FirstAvailable fields are not supported.
+type DeviceSubRequest struct {
+	// Name can be used to reference this subrequest in the list of constraints
+	// or the list of configurations for the claim. References must use the
+	// format <main request>/<subrequest>.
+	//
+	// Must be a DNS label.
+	//
+	// +required
+	Name string
+
+	// DeviceClassName references a specific DeviceClass, which can define
+	// additional configuration and selectors to be inherited by this
+	// subrequest.
+	//
+	// A class is required. Which classes are available depends on the cluster.
+	//
+	// Administrators may use this to restrict which devices may get
+	// requested by only installing classes with selectors for permitted
+	// devices. If users are free to request anything without restrictions,
+	// then administrators can create an empty DeviceClass for users
+	// to reference.
+	//
+	// +required
+	DeviceClassName string
+
+	// Selectors define criteria which must be satisfied by a specific
+	// device in order for that device to be considered for this
+	// subrequest. All selectors must be satisfied for a device to be
+	// considered.
+	//
+	// +optional
+	// +listType=atomic
+	Selectors []DeviceSelector
+
+	// AllocationMode and its related fields define how devices are allocated
+	// to satisfy this subrequest. Supported values are:
+	//
+	// - ExactCount: This request is for a specific number of devices.
+	//   This is the default. The exact number is provided in the
+	//   count field.
+	//
+	// - All: This subrequest is for all of the matching devices in a pool.
+	//   Allocation will fail if some devices are already allocated,
+	//   unless adminAccess is requested.
+	//
+	// If AlloctionMode is not specified, the default mode is ExactCount. If
+	// the mode is ExactCount and count is not specified, the default count is
+	// one. Any other subrequests must specify this field.
+	//
+	// More modes may get added in the future. Clients must refuse to handle
+	// requests with unknown modes.
+	//
+	// +optional
+	AllocationMode DeviceAllocationMode
+
+	// Count is used only when the count mode is "ExactCount". Must be greater than zero.
+	// If AllocationMode is ExactCount and this field is not specified, the default is one.
+	//
+	// +optional
+	// +oneOf=AllocationMode
+	Count int64
 }
 
 const (
-	DeviceSelectorsMaxSize = 32
+	DeviceSelectorsMaxSize             = 32
+	FirstAvailableDeviceRequestMaxSize = 8
 )
 
 type DeviceAllocationMode string
@@ -584,6 +665,10 @@ type DeviceConstraint struct {
 	// constraint. If this is not specified, this constraint applies to all
 	// requests in this claim.
 	//
+	// References to subrequests must include the name of the main request
+	// and may include the subrequest using the format <main request>[/<subrequest>]. If just
+	// the main request is given, the constraint applies to all subrequests.
+	//
 	// +optional
 	// +listType=atomic
 	Requests []string
@@ -621,6 +706,10 @@ type DeviceClaimConfiguration struct {
 	// Requests lists the names of requests where the configuration applies.
 	// If empty, it applies to all requests.
 	//
+	// References to subrequests must include the name of the main request
+	// and may include the subrequest using the format <main request>[/<subrequest>]. If just
+	// the main request is given, the configuration applies to all subrequests.
+	//
 	// +optional
 	// +listType=atomic
 	Requests []string
@@ -793,8 +882,12 @@ const AllocationResultsMaxSize = 32
 // DeviceRequestAllocationResult contains the allocation result for one request.
 type DeviceRequestAllocationResult struct {
 	// Request is the name of the request in the claim which caused this
-	// device to be allocated. Multiple devices may have been allocated
-	// per request.
+	// device to be allocated. If it references a subrequest in the
+	// firstAvailable list on a DeviceRequest, this field must
+	// include both the name of the main request and the subrequest
+	// using the format <main request>/<subrequest>.
+	//
+	// Multiple devices may have been allocated per request.
 	//
 	// +required
 	Request string
@@ -849,6 +942,10 @@ type DeviceAllocationConfiguration struct {
 	// Requests lists the names of requests where the configuration applies.
 	// If empty, its applies to all requests.
 	//
+	// References to subrequests must include the name of the main request
+	// and may include the subrequest using the format <main request>[/<subrequest>]. If just
+	// the main request is given, the configuration applies to all subrequests.
+	//
 	// +optional
 	// +listType=atomic
 	Requests []string

pkg/apis/resource/v1alpha3/defaults.go

@@ -26,6 +26,19 @@ func addDefaultingFuncs(scheme *runtime.Scheme) error {
 }
 
 func SetDefaults_DeviceRequest(obj *resourceapi.DeviceRequest) {
+	if len(obj.FirstAvailable) > 0 {
+		return
+	}
+	if obj.AllocationMode == "" {
+		obj.AllocationMode = resourceapi.DeviceAllocationModeExactCount
+	}
+
+	if obj.AllocationMode == resourceapi.DeviceAllocationModeExactCount && obj.Count == 0 {
+		obj.Count = 1
+	}
+}
+
+func SetDefaults_DeviceSubRequest(obj *resourceapi.DeviceSubRequest) {
 	if obj.AllocationMode == "" {
 		obj.AllocationMode = resourceapi.DeviceAllocationModeExactCount
 	}

pkg/apis/resource/v1alpha3/defaults_test.go

@@ -64,6 +64,72 @@ func TestSetDefaultAllocationMode(t *testing.T) {
 	assert.Equal(t, nonDefaultCount, output.Spec.Devices.Requests[0].Count)
 }
 
+func TestSetDefaultAllocationModeWithSubRequests(t *testing.T) {
+	claim := &v1alpha3.ResourceClaim{
+		Spec: v1alpha3.ResourceClaimSpec{
+			Devices: v1alpha3.DeviceClaim{
+				Requests: []v1alpha3.DeviceRequest{
+					{
+						Name: "req-1",
+						FirstAvailable: []v1alpha3.DeviceSubRequest{
+							{
+								Name: "subReq-1",
+							},
+							{
+								Name: "subReq-2",
+							},
+						},
+					},
+				},
+			},
+		},
+	}
+
+	nilValueMode := v1alpha3.DeviceAllocationMode("")
+	nilValueCount := int64(0)
+	defaultMode := v1alpha3.DeviceAllocationModeExactCount
+	defaultCount := int64(1)
+	output := roundTrip(t, runtime.Object(claim)).(*v1alpha3.ResourceClaim)
+	// fields on the top-level DeviceRequest should not change
+	assert.Equal(t, nilValueMode, output.Spec.Devices.Requests[0].AllocationMode)
+	assert.Equal(t, nilValueCount, output.Spec.Devices.Requests[0].Count)
+	// fields on the subRequests should be defaulted.
+	assert.Equal(t, defaultMode, output.Spec.Devices.Requests[0].FirstAvailable[0].AllocationMode)
+	assert.Equal(t, defaultCount, output.Spec.Devices.Requests[0].FirstAvailable[0].Count)
+	assert.Equal(t, defaultMode, output.Spec.Devices.Requests[0].FirstAvailable[1].AllocationMode)
+	assert.Equal(t, defaultCount, output.Spec.Devices.Requests[0].FirstAvailable[1].Count)
+
+	// field should not change
+	nonDefaultMode := v1alpha3.DeviceAllocationModeExactCount
+	nonDefaultCount := int64(10)
+	claim = &v1alpha3.ResourceClaim{
+		Spec: v1alpha3.ResourceClaimSpec{
+			Devices: v1alpha3.DeviceClaim{
+				Requests: []v1alpha3.DeviceRequest{{
+					Name: "req-1",
+					FirstAvailable: []v1alpha3.DeviceSubRequest{
+						{
+							Name:           "subReq-1",
+							AllocationMode: nonDefaultMode,
+							Count:          nonDefaultCount,
+						},
+						{
+							Name:           "subReq-2",
+							AllocationMode: nonDefaultMode,
+							Count:          nonDefaultCount,
+						},
+					},
+				}},
+			},
+		},
+	}
+	output = roundTrip(t, runtime.Object(claim)).(*v1alpha3.ResourceClaim)
+	assert.Equal(t, nonDefaultMode, output.Spec.Devices.Requests[0].FirstAvailable[0].AllocationMode)
+	assert.Equal(t, nonDefaultCount, output.Spec.Devices.Requests[0].FirstAvailable[0].Count)
+	assert.Equal(t, nonDefaultMode, output.Spec.Devices.Requests[0].FirstAvailable[1].AllocationMode)
+	assert.Equal(t, nonDefaultCount, output.Spec.Devices.Requests[0].FirstAvailable[1].Count)
+}
+
 func roundTrip(t *testing.T, obj runtime.Object) runtime.Object {
 	codec := legacyscheme.Codecs.LegacyCodec(v1alpha3.SchemeGroupVersion)
 	data, err := runtime.Encode(codec, obj)

pkg/apis/resource/v1beta1/defaults.go

@@ -26,6 +26,19 @@ func addDefaultingFuncs(scheme *runtime.Scheme) error {
 }
 
 func SetDefaults_DeviceRequest(obj *resourceapi.DeviceRequest) {
+	if len(obj.FirstAvailable) > 0 {
+		return
+	}
+	if obj.AllocationMode == "" {
+		obj.AllocationMode = resourceapi.DeviceAllocationModeExactCount
+	}
+
+	if obj.AllocationMode == resourceapi.DeviceAllocationModeExactCount && obj.Count == 0 {
+		obj.Count = 1
+	}
+}
+
+func SetDefaults_DeviceSubRequest(obj *resourceapi.DeviceSubRequest) {
 	if obj.AllocationMode == "" {
 		obj.AllocationMode = resourceapi.DeviceAllocationModeExactCount
 	}

pkg/apis/resource/v1beta1/defaults_test.go

@@ -64,6 +64,72 @@ func TestSetDefaultAllocationMode(t *testing.T) {
 	assert.Equal(t, nonDefaultCount, output.Spec.Devices.Requests[0].Count)
 }
 
+func TestSetDefaultAllocationModeWithSubRequests(t *testing.T) {
+	claim := &v1beta1.ResourceClaim{
+		Spec: v1beta1.ResourceClaimSpec{
+			Devices: v1beta1.DeviceClaim{
+				Requests: []v1beta1.DeviceRequest{
+					{
+						Name: "req-1",
+						FirstAvailable: []v1beta1.DeviceSubRequest{
+							{
+								Name: "subReq-1",
+							},
+							{
+								Name: "subReq-2",
+							},
+						},
+					},
+				},
+			},
+		},
+	}
+
+	nilValueMode := v1beta1.DeviceAllocationMode("")
+	nilValueCount := int64(0)
+	defaultMode := v1beta1.DeviceAllocationModeExactCount
+	defaultCount := int64(1)
+	output := roundTrip(t, runtime.Object(claim)).(*v1beta1.ResourceClaim)
+	// fields on the top-level DeviceRequest should not change
+	assert.Equal(t, nilValueMode, output.Spec.Devices.Requests[0].AllocationMode)
+	assert.Equal(t, nilValueCount, output.Spec.Devices.Requests[0].Count)
+	// fields on the subRequests should be defaulted.
+	assert.Equal(t, defaultMode, output.Spec.Devices.Requests[0].FirstAvailable[0].AllocationMode)
+	assert.Equal(t, defaultCount, output.Spec.Devices.Requests[0].FirstAvailable[0].Count)
+	assert.Equal(t, defaultMode, output.Spec.Devices.Requests[0].FirstAvailable[1].AllocationMode)
+	assert.Equal(t, defaultCount, output.Spec.Devices.Requests[0].FirstAvailable[1].Count)
+
+	// field should not change
+	nonDefaultMode := v1beta1.DeviceAllocationModeExactCount
+	nonDefaultCount := int64(10)
+	claim = &v1beta1.ResourceClaim{
+		Spec: v1beta1.ResourceClaimSpec{
+			Devices: v1beta1.DeviceClaim{
+				Requests: []v1beta1.DeviceRequest{{
+					Name: "req-1",
+					FirstAvailable: []v1beta1.DeviceSubRequest{
+						{
+							Name:           "subReq-1",
+							AllocationMode: nonDefaultMode,
+							Count:          nonDefaultCount,
+						},
+						{
+							Name:           "subReq-2",
+							AllocationMode: nonDefaultMode,
+							Count:          nonDefaultCount,
+						},
+					},
+				}},
+			},
+		},
+	}
+	output = roundTrip(t, runtime.Object(claim)).(*v1beta1.ResourceClaim)
+	assert.Equal(t, nonDefaultMode, output.Spec.Devices.Requests[0].FirstAvailable[0].AllocationMode)
+	assert.Equal(t, nonDefaultCount, output.Spec.Devices.Requests[0].FirstAvailable[0].Count)
+	assert.Equal(t, nonDefaultMode, output.Spec.Devices.Requests[0].FirstAvailable[1].AllocationMode)
+	assert.Equal(t, nonDefaultCount, output.Spec.Devices.Requests[0].FirstAvailable[1].Count)
+}
+
 func roundTrip(t *testing.T, obj runtime.Object) runtime.Object {
 	codec := legacyscheme.Codecs.LegacyCodec(v1beta1.SchemeGroupVersion)
 	data, err := runtime.Encode(codec, obj)