ResourceClaim v1beta1

ResourceClaim 描述了对集群中资源的访问请求，供工作负载使用。

apiVersion: resource.k8s.io/v1beta1

import "k8s.io/api/resource/v1beta1"

ResourceClaim

ResourceClaim 描述了对集群中资源的访问请求，供工作负载使用。例如，如果工作负载需要具有特定属性的加速器设备，则以此方式表达该请求。状态节跟踪此声明是否已满足以及已分配哪些特定资源。

这是一个 alpha 类型，需要启用 DynamicResourceAllocation 特性门控。

  • apiVersion：resource.k8s.io/v1beta1

  • kind：ResourceClaim

  • metadata（ObjectMeta）

    标准对象元数据

  • spec（ResourceClaimSpec），必需

    Spec 描述了正在请求的内容以及如何配置它。spec 是不可变的。

  • status（ResourceClaimStatus）

    Status 描述了声明是否可以使用以及已分配的内容。

ResourceClaimSpec

ResourceClaimSpec 定义了在 ResourceClaim 中请求的内容以及如何配置它。

  • controller (string)

    Controller 是指旨在处理此声明分配的 DRA 驱动程序的名称。如果为空，则分配由调度程序在调度 pod 时处理。

    必须是 DNS 子域，并且应以驱动程序供应商拥有的 DNS 域结尾。

    这是一个 alpha 字段，需要启用 DRAControlPlaneController 特性门控。

  • devices (DeviceClaim)

    Devices 定义了如何请求设备。

    DeviceClaim 定义了如何使用 ResourceClaim 请求设备。

    • devices.config ([]DeviceClaimConfiguration)

      原子性：在合并期间将被替换

      此字段包含多个潜在驱动程序的配置，这些驱动程序可以满足此声明中的请求。在分配声明时会忽略它。

      DeviceClaimConfiguration 用于 DeviceClaim 中的配置参数。

      • devices.config.opaque (OpaqueDeviceConfiguration)

        Opaque 提供了驱动程序特定的配置参数。

        OpaqueDeviceConfiguration 包含驱动程序供应商定义的格式的驱动程序配置参数。

        • devices.config.opaque.driver (string)，必需

          Driver 用于确定需要将这些配置参数传递给哪个 kubelet 插件。

          驱动程序开发人员提供的准入策略可以使用它来决定是否需要验证它们。

          必须是 DNS 子域，并且应以驱动程序供应商拥有的 DNS 域结尾。

        • devices.config.opaque.parameters (RawExtension)，必需

          Parameters 可以包含任意数据。驱动程序开发人员有责任处理验证和版本控制。通常，这包括自我标识和版本（Kubernetes 类型的 “kind” + “apiVersion”），以及不同版本之间的转换。

          *RawExtension 用于保存外部版本中的扩展。

          要使用此功能，请在外部版本化结构中使用 RawExtension 作为其类型的字段，并在内部结构中使用 Object。你还需要注册各种插件类型。

          // 内部软件包

          type MyAPIObject struct {
	runtime.TypeMeta `json:",inline"`
	MyPlugin runtime.Object `json:"myPlugin"`
}

type PluginA struct {
	AOption string `json:"aOption"`
}

          // 外部软件包

          type MyAPIObject struct {
	runtime.TypeMeta `json:",inline"`
	MyPlugin runtime.RawExtension `json:"myPlugin"`
}

type PluginA struct {
	AOption string `json:"aOption"`
}

          // 在线传输时，JSON 如下所示

          {
	"kind":"MyAPIObject",
	"apiVersion":"v1",
	"myPlugin": {
		"kind":"PluginA",
		"aOption":"foo",
	},
}

          那么会发生什么？首先，解码使用 JSON 或 YAML 将序列化的数据解组到外部 MyAPIObject 中。这会导致存储原始 JSON，但不会解包。下一步是复制（使用 pkg/conversion）到内部结构中。runtime 包的 DefaultScheme 安装了转换函数，这些函数将解包 RawExtension 中存储的 JSON，将其转换为正确的对象类型，并将其存储在 Object 中。（TODO：如果对象类型未知，则将创建并存储 runtime.Unknown 对象。）*

      • devices.config.requests ([]string)

        原子性：在合并期间将被替换

        Requests 列出了配置适用的请求的名称。如果为空，则适用于所有请求。

    • devices.constraints ([]DeviceConstraint)

      原子性：在合并期间将被替换

      分配给声明的设备集必须满足这些约束。

      DeviceConstraint 除了 Requests 外，必须恰好设置一个字段。

      • devices.constraints.matchAttribute (string)

        MatchAttribute 要求相关的所有设备都具有此属性，并且该属性的类型和值在这些设备之间相同。

        例如，如果你指定了 “dra.example.com/numa”（一个假设的例子！），那么只会选择同一 NUMA 节点中的设备。不具有该属性的设备将不会被选择。所有设备都应为此属性使用相同类型的值，因为这是其规范的一部分，但如果某个设备没有这样做，那么它也不会被选择。

        必须包含域限定符。

      • devices.constraints.requests ([]string)

        原子性：在合并期间将被替换

        Requests 是此声明中必须共同满足此约束的一个或多个请求的列表。如果一个请求由多个设备满足，那么所有设备都必须满足该约束。如果未指定，则此约束适用于此声明中的所有请求。

    • devices.requests ([]DeviceRequest)

      原子性：在合并期间将被替换

      Requests 表示对必须全部满足的不同设备的单个请求。如果为空，则无需分配任何内容。

      *DeviceRequest 是对声明所需的设备的请求。这通常是对单个资源（如设备）的请求，但也可能请求多个相同的设备。

      当前需要 DeviceClassName。客户端必须检查它是否确实已设置。它的缺失表明某些更改的客户端尚不支持，在这种情况下，它必须拒绝处理该请求。*

      • devices.requests.deviceClassName (string)，必需

        DeviceClassName 引用特定的 DeviceClass，该 DeviceClass 可以定义要由此请求继承的其他配置和选择器。

        需要一个类。哪些类可用取决于集群。

        管理员可以使用它来限制可能请求哪些设备，方法是仅安装具有允许设备的 selector 的类。如果用户可以自由地请求任何内容而没有限制，那么管理员可以创建一个空的 DeviceClass 供用户引用。

      • devices.requests.name (string)，必需

        Name 可用于在 pod.spec.containers[].resources.claims 条目和声明的约束中引用此请求。

        必须是 DNS 标签。

      • devices.requests.adminAccess (boolean)

        AdminAccess 表示这是对设备管理访问权限的声明。具有 AdminAccess 的声明预计将用于设备的监视或其他管理服务。它们忽略对设备的普通声明，包括访问模式和任何资源分配。

      • devices.requests.allocationMode (string)

        AllocationMode 及其相关字段定义了如何分配设备以满足此请求。支持的值为

        • ExactCount：此请求是针对特定数量的设备。这是默认设置。确切的数量在 count 字段中提供。

        • 全部：此请求适用于池中所有匹配的设备。如果某些设备已被分配，则分配将失败，除非请求了 adminAccess。

        如果未指定 AlloctionMode，则默认模式为 ExactCount。如果模式为 ExactCount 且未指定 count，则默认计数为 1。任何其他请求都必须指定此字段。

        将来可能会添加更多模式。客户端必须拒绝处理未知模式的请求。

      • devices.requests.count (int64)

        仅当计数模式为 "ExactCount" 时才使用 Count。必须大于零。如果 AllocationMode 为 ExactCount 且未指定此字段，则默认值为 1。

      • devices.requests.selectors ([]DeviceSelector)

        原子性：在合并期间将被替换

        选择器定义了特定设备必须满足的条件，以便将该设备考虑用于此请求。要考虑某个设备，必须满足所有选择器。

        DeviceSelector 必须只设置一个字段。

        • devices.requests.selectors.cel (CELDeviceSelector)

          CEL 包含用于选择设备的 CEL 表达式。

          CELDeviceSelector 包含用于选择设备的 CEL 表达式。

          • devices.requests.selectors.cel.expression (string), 必填

            Expression 是一个 CEL 表达式，用于评估单个设备。当正在考虑的设备满足所需条件时，它必须评估为 true；当不满足时，它必须评估为 false。任何其他结果都是错误，会导致设备分配中止。

            表达式的输入是一个名为 "device" 的对象，该对象具有以下属性：

            • driver (string)：定义此设备的驱动程序的名称。
            • attributes (map[string]object)：设备的属性，按前缀分组（例如，device.attributes["dra.example.com"] 评估为一个对象，其中包含所有前缀为 "dra.example.com" 的属性）。
            • capacity (map[string]object)：设备的容量，按前缀分组。

            示例：考虑一个 driver="dra.example.com" 的设备，它公开了两个名为 "model" 和 "ext.example.com/family" 的属性，并公开了一个名为 "modules" 的容量。此表达式的输入将具有以下字段：

            device.driver
device.attributes["dra.example.com"].model
device.attributes["ext.example.com"].family
device.capacity["dra.example.com"].modules

            device.driver 字段可用于检查特定驱动程序，可以作为高级先决条件（即，你只想考虑来自此驱动程序的设备），也可以作为旨在考虑来自不同驱动程序的设备的多子句表达式的一部分。

            每个属性的值类型由设备定义定义，编写这些表达式的用户必须查阅其特定驱动程序的文档。每个容量的值类型为 Quantity。

            如果未知前缀用作 device.attributes 或 device.capacity 中的查找，则将返回空映射。任何对未知字段的引用都将导致评估错误并中止分配。

            健壮的表达式应在引用属性之前检查属性是否存在。

            为了便于使用，启用了 cel.bind() 函数，可用于简化访问具有相同域的多个属性的表达式。例如

            cel.bind(dra, device.attributes["dra.example.com"], dra.someBool && dra.anotherBool)

ResourceClaimStatus

ResourceClaimStatus 跟踪资源是否已被分配以及分配的结果是什么。

  • allocation (AllocationResult)

    一旦声明已成功分配，就会设置 Allocation。

    AllocationResult 包含已分配资源的属性。

    • allocation.controller (string)

      Controller 是处理分配的 DRA 驱动程序的名称。该驱动程序还负责取消分配声明。当可以在不涉及驱动程序的情况下取消分配声明时，它为空。

      驱动程序可以分配其他驱动程序提供的设备，因此此处的驱动程序名称可能与结果中列出的驱动程序名称不同。

      这是一个 alpha 字段，需要启用 DRAControlPlaneController 特性门控。

    • allocation.devices (DeviceAllocationResult)

      Devices 是分配设备的结果。

      DeviceAllocationResult 是分配设备的结果。

      • allocation.devices.config ([]DeviceAllocationConfiguration)

        原子性：在合并期间将被替换

        此字段是所有声明和类配置参数的组合。驱动程序可以根据标志区分它们。

        这包括结果中没有分配设备的驱动程序的配置参数，因为这取决于驱动程序支持哪些配置参数。它们可以默默地忽略未知的配置参数。

        DeviceAllocationConfiguration 嵌入到 AllocationResult 中。

        • allocation.devices.config.source (string), 必填

          Source 记录配置是来自类，因此普通用户无法设置，还是来自声明。

        • allocation.devices.config.opaque (OpaqueDeviceConfiguration)

          Opaque 提供了驱动程序特定的配置参数。

          OpaqueDeviceConfiguration 包含驱动程序供应商定义的格式的驱动程序配置参数。

          • allocation.devices.config.opaque.driver (string), 必填

            Driver 用于确定需要将这些配置参数传递给哪个 kubelet 插件。

            驱动程序开发人员提供的准入策略可以使用它来决定是否需要验证它们。

            必须是 DNS 子域，并且应以驱动程序供应商拥有的 DNS 域结尾。

          • allocation.devices.config.opaque.parameters (RawExtension), 必填

            Parameters 可以包含任意数据。驱动程序开发人员有责任处理验证和版本控制。通常，这包括自我标识和版本（Kubernetes 类型的 “kind” + “apiVersion”），以及不同版本之间的转换。

            *RawExtension 用于保存外部版本中的扩展。

            要使用此功能，请在外部版本化结构中使用 RawExtension 作为其类型的字段，并在内部结构中使用 Object。你还需要注册各种插件类型。

            // 内部软件包

            type MyAPIObject struct { runtime.TypeMeta json:",inline" MyPlugin runtime.Object json:"myPlugin" }

            type PluginA struct { AOption string json:"aOption" }

            // 外部软件包

            type MyAPIObject struct { runtime.TypeMeta json:",inline" MyPlugin runtime.RawExtension json:"myPlugin" }

            type PluginA struct { AOption string json:"aOption" }

            // 在线传输时，JSON 如下所示

            { "kind":"MyAPIObject", "apiVersion":"v1", "myPlugin": { "kind":"PluginA", "aOption":"foo", }, }

            那么会发生什么？首先，解码使用 JSON 或 YAML 将序列化的数据解组到外部 MyAPIObject 中。这会导致存储原始 JSON，但不会解包。下一步是复制（使用 pkg/conversion）到内部结构中。runtime 包的 DefaultScheme 安装了转换函数，这些函数将解包 RawExtension 中存储的 JSON，将其转换为正确的对象类型，并将其存储在 Object 中。（TODO：如果对象类型未知，则将创建并存储 runtime.Unknown 对象。）*

        • allocation.devices.config.requests ([]string)

          原子性：在合并期间将被替换

          Requests 列出配置适用的请求的名称。如果为空，则适用于所有请求。

      • allocation.devices.results ([]DeviceRequestAllocationResult)

        原子性：在合并期间将被替换

        Results 列出所有已分配的设备。

        DeviceRequestAllocationResult 包含一个请求的分配结果。

        • allocation.devices.results.device (string), 必填

          Device 通过其在驱动程序资源池中的名称引用一个设备实例。它必须是 DNS 标签。

        • allocation.devices.results.driver (string), 必填

          Driver 指定 DRA 驱动程序的名称，该驱动程序的 kubelet 插件应在节点上需要声明时调用以处理分配。

          必须是 DNS 子域，并且应以驱动程序供应商拥有的 DNS 域结尾。

        • allocation.devices.results.pool (string), 必填

          此名称与驱动程序名称和设备名称字段一起标识分配了哪个设备 (\<驱动程序名称>/\<池名称>/\<设备名称>)。

          长度不得超过 253 个字符，并且可能包含一个或多个以斜杠分隔的 DNS 子域。

        • allocation.devices.results.request (string), 必填

          Request 是声明中导致分配此设备的请求的名称。每个请求可能已分配多个设备。

    • allocation.nodeSelector (NodeSelector)

      NodeSelector 定义分配的资源在何处可用。如果未设置，则它们在所有位置都可用。

      节点选择器表示对一组节点的一个或多个标签查询结果的并集；也就是说，它表示节点选择器术语所表示的选择器的 OR。

      • allocation.nodeSelector.nodeSelectorTerms ([]NodeSelectorTerm), 必填

        原子性：在合并期间将被替换

        必填。节点选择器术语的列表。这些术语是 ORed 的。

        空或空节点选择器术语不匹配任何对象。它们的的要求是 ANDed 的。TopologySelectorTerm 类型实现了 NodeSelectorTerm 的一个子集。

        • allocation.nodeSelector.nodeSelectorTerms.matchExpressions ([]NodeSelectorRequirement)

          原子性：在合并期间将被替换

          按节点的标签列出的节点选择器要求列表。

        • allocation.nodeSelector.nodeSelectorTerms.matchFields ([]NodeSelectorRequirement)

          原子性：在合并期间将被替换

          按节点的字段列出的节点选择器要求列表。

  • deallocationRequested (boolean)

    表示要取消分配声明。当设置此项时，不能向 ReservedFor 添加新的使用者。

    仅当需要 DRA 驱动程序取消分配声明时才使用此项。然后，该驱动程序必须取消分配此声明并重置该字段以及清除 Allocation 字段。

    这是一个 alpha 字段，需要启用 DRAControlPlaneController 特性门控。

  • reservedFor ([]ResourceClaimConsumerReference)

    补丁策略：合并键 uid

    映射：在合并期间将保留键 uid 上的唯一值

    ReservedFor 指示当前允许使用声明的实体。未为该 Pod 预留的引用 ResourceClaim 的 Pod 将不会启动。正在使用或可能正在使用（因为它已被预留）的声明不得被取消分配。

    在具有多个调度程序实例的集群中，两个 Pod 可能会由不同的调度程序同时调度。当它们引用同一个已达到其最大使用者数量的 ResourceClaim 时，只能调度一个 Pod。

    两个调度程序都尝试将其 Pod 添加到 claim.status.reservedFor 字段，但只有先到达 API 服务器的更新才会被存储。另一个更新失败并出现错误，并且发出此错误的调度程序知道它必须将 Pod 放回队列，等待 ResourceClaim 再次变为可用。

    最多可以有 32 个此类预留。将来可能会增加，但不会减少。

    ResourceClaimConsumerReference 包含足够的信息，使您可以找到 ResourceClaim 的使用者。用户必须是与 ResourceClaim 位于同一命名空间中的资源。

    • reservedFor.name (string), 必填

      Name 是被引用资源的名称。

    • reservedFor.resource (string), 必填

      Resource 是被引用资源的类型，例如“pods”。

    • reservedFor.uid (string), 必填

      UID 确切地标识资源的某个实例。

    • reservedFor.apiGroup (string)

      APIGroup 是被引用资源的组。对于核心 API，它为空。这与创建资源时使用的 APIVersion 中的组匹配。

ResourceClaimList

ResourceClaimList 是声明的集合。

  • apiVersion：resource.k8s.io/v1beta1

  • kind: ResourceClaimList

  • metadata (ListMeta)

    标准列表元数据

  • items ([]ResourceClaim), 必填

    Items 是资源声明的列表。

操作

get 读取指定的 ResourceClaim

HTTP 请求

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

参数

  • name (in path): string, 必填

    ResourceClaim 的名称

  • namespace (in path): string, 必填

    命名空间

  • pretty (in query): string

    pretty

响应

200 (ResourceClaim): OK

401: 未经授权

get 读取指定 ResourceClaim 的状态

HTTP 请求

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

参数

  • name (in path): string, 必填

    ResourceClaim 的名称

  • namespace (in path): string, 必填

    命名空间

  • pretty (in query): string

    pretty

响应

200 (ResourceClaim): OK

401: 未经授权

list 列出或监视类型为 ResourceClaim 的对象

HTTP 请求

GET /apis/resource.k8s.io/v1beta1/namespaces/{namespace}/resourceclaims

参数

响应

200 (ResourceClaimList): OK

401: 未经授权

list 列出或监视类型为 ResourceClaim 的对象

HTTP 请求

GET /apis/resource.k8s.io/v1beta1/resourceclaims

参数

响应

200 (ResourceClaimList): OK

401: 未经授权

create 创建 ResourceClaim

HTTP 请求

POST /apis/resource.k8s.io/v1beta1/namespaces/{namespace}/resourceclaims

参数

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

202 (ResourceClaim): 已接受

401: 未经授权

update 替换指定的 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

401: 未经授权

update 替换指定 ResourceClaim 的状态

HTTP 请求

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

参数

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

401: 未经授权

patch 部分更新指定的 ResourceClaim

HTTP 请求

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

参数

  • name (in path): string, 必填

    ResourceClaim 的名称

  • namespace (in path): string, 必填

    命名空间

  • body: Patch，必需

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (查询参数): 布尔值

    强制

  • pretty (in query): string

    pretty

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

401: 未经授权

patch 部分更新指定 ResourceClaim 的状态

HTTP 请求

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

参数

  • name (in path): string, 必填

    ResourceClaim 的名称

  • namespace (in path): string, 必填

    命名空间

  • body: Patch，必需

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (查询参数): 布尔值

    强制

  • pretty (in query): string

    pretty

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

401: 未经授权

delete 删除一个 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): OK

202 (ResourceClaim): 已接受

401: 未经授权

deletecollection 删除 ResourceClaim 的集合

HTTP 请求

DELETE /apis/resource.k8s.io/v1beta1/namespaces/{namespace}/resourceclaims

参数

响应

200 (Status): OK

401: 未经授权

此页面为自动生成。

如果您计划报告此页面的问题，请在您的问题描述中提及该页面是自动生成的。修复可能需要在 Kubernetes 项目的其他地方进行。

最后修改时间为太平洋标准时间 2024 年 11 月 19 日 上午 11:15：DRA: 包含 v1beta1 API 参考 (26b5da0885)