ResourceClaim [resource.k8s.io/v1alpha2] - Schedule and quota APIs | API reference

Specification
API endpoints

Description

ResourceClaim describes which resources are needed by a resource consumer. Its status tracks whether the resource has been allocated and what the resulting attributes are.

This is an alpha type and requires enabling the DynamicResourceAllocation feature gate.

Type

object

Required

spec

Specification

Property Type Description

Property	Type	Description
`apiVersion`	`string`	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`kind`	`string`	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata`	`ObjectMeta`	Standard object metadata
`spec`	`object`	ResourceClaimSpec defines how a resource is to be allocated.
`status`	`object`	ResourceClaimStatus tracks whether the resource has been allocated and what the resulting attributes are.

apiVersion

string

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

kind

string

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

metadata

ObjectMeta

Standard object metadata

spec

object

ResourceClaimSpec defines how a resource is to be allocated.

status

object

ResourceClaimStatus tracks whether the resource has been allocated and what the resulting attributes are.

.spec

Description

ResourceClaimSpec defines how a resource is to be allocated.

Type

object

Required

resourceClassName

Property Type Description

Property	Type	Description
`allocationMode`	`string`	Allocation can start immediately or when a Pod wants to use the resource. "WaitForFirstConsumer" is the default.
`parametersRef`	`object`	ResourceClaimParametersReference contains enough information to let you locate the parameters for a ResourceClaim. The object must be in the same namespace as the ResourceClaim.
`resourceClassName`	`string`	ResourceClassName references the driver and additional parameters via the name of a ResourceClass that was created as part of the driver deployment.

allocationMode

string

Allocation can start immediately or when a Pod wants to use the resource. "WaitForFirstConsumer" is the default.

parametersRef

object

ResourceClaimParametersReference contains enough information to let you locate the parameters for a ResourceClaim. The object must be in the same namespace as the ResourceClaim.

resourceClassName

string

ResourceClassName references the driver and additional parameters via the name of a ResourceClass that was created as part of the driver deployment.

.spec.parametersRef

Description

ResourceClaimParametersReference contains enough information to let you locate the parameters for a ResourceClaim. The object must be in the same namespace as the ResourceClaim.

Type

object

Required

kind
name

Property Type Description

Property	Type	Description
`apiGroup`	`string`	APIGroup is the group for the resource being referenced. It is empty for the core API. This matches the group in the APIVersion that is used when creating the resources.
`kind`	`string`	Kind is the type of resource being referenced. This is the same value as in the parameter object’s metadata, for example "ConfigMap".
`name`	`string`	Name is the name of resource being referenced.

apiGroup

string

APIGroup is the group for the resource being referenced. It is empty for the core API. This matches the group in the APIVersion that is used when creating the resources.

kind

string

Kind is the type of resource being referenced. This is the same value as in the parameter object’s metadata, for example "ConfigMap".

name

string

Name is the name of resource being referenced.

.status

Description: ResourceClaimStatus tracks whether the resource has been allocated and what the resulting attributes are.
Type: object

Property Type Description

Property	Type	Description
`allocation`	`object`	AllocationResult contains attributes of an allocated resource.
`deallocationRequested`	`boolean`	DeallocationRequested indicates that a ResourceClaim is to be deallocated. The driver then must deallocate this claim and reset the field together with clearing the Allocation field. While DeallocationRequested is set, no new consumers may be added to ReservedFor.
`driverName`	`string`	DriverName is a copy of the driver name from the ResourceClass at the time when allocation started.
`reservedFor`	`array`	ReservedFor indicates which entities are currently allowed to use the claim. A Pod which references a ResourceClaim which is not reserved for that Pod will not be started. There can be at most 32 such reservations. This may get increased in the future, but not reduced.
`reservedFor[]`	`object`	ResourceClaimConsumerReference contains enough information to let you locate the consumer of a ResourceClaim. The user must be a resource in the same namespace as the ResourceClaim.

allocation

object

AllocationResult contains attributes of an allocated resource.

deallocationRequested

boolean

DeallocationRequested indicates that a ResourceClaim is to be deallocated.

The driver then must deallocate this claim and reset the field together with clearing the Allocation field.

While DeallocationRequested is set, no new consumers may be added to ReservedFor.

driverName

string

DriverName is a copy of the driver name from the ResourceClass at the time when allocation started.

reservedFor

array

ReservedFor indicates which entities are currently allowed to use the claim. A Pod which references a ResourceClaim which is not reserved for that Pod will not be started.

There can be at most 32 such reservations. This may get increased in the future, but not reduced.

reservedFor[]

object

ResourceClaimConsumerReference contains enough information to let you locate the consumer of a ResourceClaim. The user must be a resource in the same namespace as the ResourceClaim.

.status.allocation

Description: AllocationResult contains attributes of an allocated resource.
Type: object

Property Type Description

Property	Type	Description
`availableOnNodes`	`NodeSelector`	This field will get set by the resource driver after it has allocated the resource to inform the scheduler where it can schedule Pods using the ResourceClaim. Setting this field is optional. If null, the resource is available everywhere.
`resourceHandles`	`array`	ResourceHandles contain the state associated with an allocation that should be maintained throughout the lifetime of a claim. Each ResourceHandle contains data that should be passed to a specific kubelet plugin once it lands on a node. This data is returned by the driver after a successful allocation and is opaque to Kubernetes. Driver documentation may explain to users how to interpret this data if needed. Setting this field is optional. It has a maximum size of 32 entries. If null (or empty), it is assumed this allocation will be processed by a single kubelet plugin with no ResourceHandle data attached. The name of the kubelet plugin invoked will match the DriverName set in the ResourceClaimStatus this AllocationResult is embedded in.
`resourceHandles[]`	`object`	ResourceHandle holds opaque resource data for processing by a specific kubelet plugin.
`shareable`	`boolean`	Shareable determines whether the resource supports more than one consumer at a time.

availableOnNodes

NodeSelector

This field will get set by the resource driver after it has allocated the resource to inform the scheduler where it can schedule Pods using the ResourceClaim.

Setting this field is optional. If null, the resource is available everywhere.

resourceHandles

array

ResourceHandles contain the state associated with an allocation that should be maintained throughout the lifetime of a claim. Each ResourceHandle contains data that should be passed to a specific kubelet plugin once it lands on a node. This data is returned by the driver after a successful allocation and is opaque to Kubernetes. Driver documentation may explain to users how to interpret this data if needed.

Setting this field is optional. It has a maximum size of 32 entries. If null (or empty), it is assumed this allocation will be processed by a single kubelet plugin with no ResourceHandle data attached. The name of the kubelet plugin invoked will match the DriverName set in the ResourceClaimStatus this AllocationResult is embedded in.

resourceHandles[]

object

ResourceHandle holds opaque resource data for processing by a specific kubelet plugin.

shareable

boolean

Shareable determines whether the resource supports more than one consumer at a time.

.status.allocation.resourceHandles

Description: ResourceHandles contain the state associated with an allocation that should be maintained throughout the lifetime of a claim. Each ResourceHandle contains data that should be passed to a specific kubelet plugin once it lands on a node. This data is returned by the driver after a successful allocation and is opaque to Kubernetes. Driver documentation may explain to users how to interpret this data if needed.

Setting this field is optional. It has a maximum size of 32 entries. If null (or empty), it is assumed this allocation will be processed by a single kubelet plugin with no ResourceHandle data attached. The name of the kubelet plugin invoked will match the DriverName set in the ResourceClaimStatus this AllocationResult is embedded in.
Type: array

.status.allocation.resourceHandles[]

Description: ResourceHandle holds opaque resource data for processing by a specific kubelet plugin.
Type: object

Property Type Description

Property	Type	Description
`data`	`string`	Data contains the opaque data associated with this ResourceHandle. It is set by the controller component of the resource driver whose name matches the DriverName set in the ResourceClaimStatus this ResourceHandle is embedded in. It is set at allocation time and is intended for processing by the kubelet plugin whose name matches the DriverName set in this ResourceHandle. The maximum size of this field is 16KiB. This may get increased in the future, but not reduced.
`driverName`	`string`	DriverName specifies the name of the resource driver whose kubelet plugin should be invoked to process this ResourceHandle’s data once it lands on a node. This may differ from the DriverName set in ResourceClaimStatus this ResourceHandle is embedded in.
`structuredData`	`object`	StructuredResourceHandle is the in-tree representation of the allocation result.

data

string

Data contains the opaque data associated with this ResourceHandle. It is set by the controller component of the resource driver whose name matches the DriverName set in the ResourceClaimStatus this ResourceHandle is embedded in. It is set at allocation time and is intended for processing by the kubelet plugin whose name matches the DriverName set in this ResourceHandle.

The maximum size of this field is 16KiB. This may get increased in the future, but not reduced.

driverName

string

DriverName specifies the name of the resource driver whose kubelet plugin should be invoked to process this ResourceHandle’s data once it lands on a node. This may differ from the DriverName set in ResourceClaimStatus this ResourceHandle is embedded in.

structuredData

object

StructuredResourceHandle is the in-tree representation of the allocation result.

.status.allocation.resourceHandles[].structuredData

Description

StructuredResourceHandle is the in-tree representation of the allocation result.

Type

object

Required

results

Property Type Description

Property	Type	Description
`nodeName`	`string`	NodeName is the name of the node providing the necessary resources if the resources are local to a node.
`results`	`array`	Results lists all allocated driver resources.
`results[]`	`object`	DriverAllocationResult contains vendor parameters and the allocation result for one request.
`vendorClaimParameters`	`RawExtension`	VendorClaimParameters are the per-claim configuration parameters from the resource claim parameters at the time that the claim was allocated.
`vendorClassParameters`	`RawExtension`	VendorClassParameters are the per-claim configuration parameters from the resource class at the time that the claim was allocated.

nodeName

string

NodeName is the name of the node providing the necessary resources if the resources are local to a node.

results

array

Results lists all allocated driver resources.

results[]

object

DriverAllocationResult contains vendor parameters and the allocation result for one request.

vendorClaimParameters

RawExtension

VendorClaimParameters are the per-claim configuration parameters from the resource claim parameters at the time that the claim was allocated.

vendorClassParameters

RawExtension

VendorClassParameters are the per-claim configuration parameters from the resource class at the time that the claim was allocated.

.status.allocation.resourceHandles[].structuredData.results

Description: Results lists all allocated driver resources.
Type: array

.status.allocation.resourceHandles[].structuredData.results[]

Description: DriverAllocationResult contains vendor parameters and the allocation result for one request.
Type: object

Property Type Description

Property	Type	Description
`namedResources`	`object`	NamedResourcesAllocationResult is used in AllocationResultModel.
`vendorRequestParameters`	`RawExtension`	VendorRequestParameters are the per-request configuration parameters from the time that the claim was allocated.

namedResources

object

NamedResourcesAllocationResult is used in AllocationResultModel.

vendorRequestParameters

RawExtension

VendorRequestParameters are the per-request configuration parameters from the time that the claim was allocated.

.status.allocation.resourceHandles[].structuredData.results[].namedResources

Description

NamedResourcesAllocationResult is used in AllocationResultModel.

Type

object

Required

name

Property Type Description

Property	Type	Description
`name`	`string`	Name is the name of the selected resource instance.

name

string

Name is the name of the selected resource instance.

.status.reservedFor

Description: ReservedFor indicates which entities are currently allowed to use the claim. A Pod which references a ResourceClaim which is not reserved for that Pod will not be started.

There can be at most 32 such reservations. This may get increased in the future, but not reduced.
Type: array

.status.reservedFor[]

Description

ResourceClaimConsumerReference contains enough information to let you locate the consumer of a ResourceClaim. The user must be a resource in the same namespace as the ResourceClaim.

Type

object

Required

resource
name
uid

Property Type Description

Property	Type	Description
`apiGroup`	`string`	APIGroup is the group for the resource being referenced. It is empty for the core API. This matches the group in the APIVersion that is used when creating the resources.
`name`	`string`	Name is the name of resource being referenced.
`resource`	`string`	Resource is the type of resource being referenced, for example "pods".
`uid`	`string`	UID identifies exactly one incarnation of the resource.

apiGroup

string

APIGroup is the group for the resource being referenced. It is empty for the core API. This matches the group in the APIVersion that is used when creating the resources.

name

string

Name is the name of resource being referenced.

resource

string

Resource is the type of resource being referenced, for example "pods".

uid

string

UID identifies exactly one incarnation of the resource.

API endpoints

The following API endpoints are available:

/apis/resource.k8s.io/v1alpha2/resourceclaims
- GET: list or watch objects of kind ResourceClaim
/apis/resource.k8s.io/v1alpha2/watch/resourceclaims
- GET: watch individual changes to a list of ResourceClaim. deprecated: use the 'watch' parameter with a list operation instead.
/apis/resource.k8s.io/v1alpha2/namespaces/{namespace}/resourceclaims
- DELETE: delete collection of ResourceClaim
- GET: list or watch objects of kind ResourceClaim
- POST: create a ResourceClaim
/apis/resource.k8s.io/v1alpha2/watch/namespaces/{namespace}/resourceclaims
- GET: watch individual changes to a list of ResourceClaim. deprecated: use the 'watch' parameter with a list operation instead.
/apis/resource.k8s.io/v1alpha2/namespaces/{namespace}/resourceclaims/{name}
- DELETE: delete a ResourceClaim
- GET: read the specified ResourceClaim
- PATCH: partially update the specified ResourceClaim
- PUT: replace the specified ResourceClaim
/apis/resource.k8s.io/v1alpha2/watch/namespaces/{namespace}/resourceclaims/{name}
- GET: watch changes to an object of kind ResourceClaim. deprecated: use the 'watch' parameter with a list operation instead, filtered to a single item with the 'fieldSelector' parameter.
/apis/resource.k8s.io/v1alpha2/namespaces/{namespace}/resourceclaims/{name}/status
- GET: read status of the specified ResourceClaim
- PATCH: partially update status of the specified ResourceClaim
- PUT: replace status of the specified ResourceClaim

/apis/resource.k8s.io/v1alpha2/resourceclaims

HTTP method: GET
Description: list or watch objects of kind ResourceClaim

Table 1. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaimList` schema
401 - Unauthorized	Empty

/apis/resource.k8s.io/v1alpha2/watch/resourceclaims

HTTP method: GET
Description: watch individual changes to a list of ResourceClaim. deprecated: use the 'watch' parameter with a list operation instead.

Table 2. HTTP responses
HTTP code	Reponse body
200 - OK	`WatchEvent` schema
401 - Unauthorized	Empty

/apis/resource.k8s.io/v1alpha2/namespaces/{namespace}/resourceclaims

HTTP method: DELETE
Description: delete collection of ResourceClaim

Table 3. Query parameters
Parameter	Type	Description
`dryRun`	`string`	When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed

Table 4. HTTP responses
HTTP code	Reponse body
200 - OK	`Status` schema
401 - Unauthorized	Empty

HTTP method: GET
Description: list or watch objects of kind ResourceClaim

Table 5. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaimList` schema
401 - Unauthorized	Empty

HTTP method: POST
Description: create a ResourceClaim

Table 6. Query parameters
Parameter	Type	Description
`dryRun`	`string`	When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
`fieldValidation`	`string`	fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

Table 7. Body parameters
Parameter	Type	Description
`body`	`ResourceClaim` schema

Table 8. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaim` schema
201 - Created	`ResourceClaim` schema
202 - Accepted	`ResourceClaim` schema
401 - Unauthorized	Empty

/apis/resource.k8s.io/v1alpha2/watch/namespaces/{namespace}/resourceclaims

HTTP method: GET
Description: watch individual changes to a list of ResourceClaim. deprecated: use the 'watch' parameter with a list operation instead.

Table 9. HTTP responses
HTTP code	Reponse body
200 - OK	`WatchEvent` schema
401 - Unauthorized	Empty

/apis/resource.k8s.io/v1alpha2/namespaces/{namespace}/resourceclaims/{name}

Table 10. Global path parameters
Parameter	Type	Description
`name`	`string`	name of the ResourceClaim

HTTP method: DELETE
Description: delete a ResourceClaim

Table 11. Query parameters
Parameter	Type	Description
`dryRun`	`string`	When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed

Table 12. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaim` schema
202 - Accepted	`ResourceClaim` schema
401 - Unauthorized	Empty

HTTP method: GET
Description: read the specified ResourceClaim

Table 13. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaim` schema
401 - Unauthorized	Empty

HTTP method: PATCH
Description: partially update the specified ResourceClaim

Table 14. Query parameters
Parameter	Type	Description
`dryRun`	`string`	When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
`fieldValidation`	`string`	fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

Table 15. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaim` schema
201 - Created	`ResourceClaim` schema
401 - Unauthorized	Empty

HTTP method: PUT
Description: replace the specified ResourceClaim

Table 16. Query parameters
Parameter	Type	Description
`dryRun`	`string`	When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
`fieldValidation`	`string`	fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

Table 17. Body parameters
Parameter	Type	Description
`body`	`ResourceClaim` schema

Table 18. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaim` schema
201 - Created	`ResourceClaim` schema
401 - Unauthorized	Empty

/apis/resource.k8s.io/v1alpha2/watch/namespaces/{namespace}/resourceclaims/{name}

Table 19. Global path parameters
Parameter	Type	Description
`name`	`string`	name of the ResourceClaim

HTTP method: GET
Description: watch changes to an object of kind ResourceClaim. deprecated: use the 'watch' parameter with a list operation instead, filtered to a single item with the 'fieldSelector' parameter.

Table 20. HTTP responses
HTTP code	Reponse body
200 - OK	`WatchEvent` schema
401 - Unauthorized	Empty

/apis/resource.k8s.io/v1alpha2/namespaces/{namespace}/resourceclaims/{name}/status

Table 21. Global path parameters
Parameter	Type	Description
`name`	`string`	name of the ResourceClaim

HTTP method: GET
Description: read status of the specified ResourceClaim

Table 22. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaim` schema
401 - Unauthorized	Empty

HTTP method: PATCH
Description: partially update status of the specified ResourceClaim

Table 23. Query parameters
Parameter	Type	Description
`dryRun`	`string`	When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
`fieldValidation`	`string`	fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

Table 24. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaim` schema
201 - Created	`ResourceClaim` schema
401 - Unauthorized	Empty

HTTP method: PUT
Description: replace status of the specified ResourceClaim

Table 25. Query parameters
Parameter	Type	Description
`dryRun`	`string`	When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
`fieldValidation`	`string`	fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.

Table 26. Body parameters
Parameter	Type	Description
`body`	`ResourceClaim` schema

Table 27. HTTP responses
HTTP code	Reponse body
200 - OK	`ResourceClaim` schema
201 - Created	`ResourceClaim` schema
401 - Unauthorized	Empty