ResourceClaim v1alpha3

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

apiVersion: resource.k8s.io/v1alpha3

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

ResourceClaim

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

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

  • apiVersion: resource.k8s.io/v1alpha3

  • kind: ResourceClaim

  • metadata (ObjectMeta)

    标准对象元数据

  • spec (ResourceClaimSpec), 必需

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

  • status (ResourceClaimStatus)

    状态描述声明是否准备好使用以及已分配的内容。

ResourceClaimSpec

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

  • 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 (字符串), 必需

          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 ([]字符串)

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

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

    • devices.constraints ([]DeviceConstraint)

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

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

      DeviceConstraint 除了 Requests 之外必须正好设置一个字段。

      • devices.constraints.matchAttribute (字符串)

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

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

        必须包含域限定符。

      • devices.constraints.requests ([]字符串)

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

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

    • devices.requests ([]DeviceRequest)

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

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

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

      目前需要 DeviceClassName。 客户端必须检查它是否已设置。 它的不存在表示某些内容以客户端尚不支持的方式发生了更改，在这种情况下，它必须拒绝处理该请求。*

      • devices.requests.deviceClassName (字符串), 必需

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

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

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

      • devices.requests.name (字符串), 必需

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

        必须是 DNS 标签。

      • devices.requests.adminAccess (布尔值)

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

      • devices.requests.allocationMode (字符串)

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

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

        • All：此请求是针对池中的所有匹配设备。 如果已分配某些设备，则分配将失败，除非请求 adminAccess。

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

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

      • 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 (字符串), 必需

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

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

            • driver (字符串)：定义此设备的驱动程序的名称。
            • 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 (字符串)

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

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

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

    • allocation.devices (DeviceAllocationResult)

      Devices 是分配设备的结果。

      DeviceAllocationResult 是分配设备的结果。

      • allocation.devices.config ([]DeviceAllocationConfiguration)

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

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

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

        DeviceAllocationConfiguration 嵌入到 AllocationResult 中。

        • allocation.devices.config.source (字符串), 必需

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

        • allocation.devices.config.opaque (OpaqueDeviceConfiguration)

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

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

          • allocation.devices.config.opaque.driver (字符串), 必需

            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 ([]字符串)

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

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

      • allocation.devices.results ([]DeviceRequestAllocationResult)

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

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

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

        • allocation.devices.results.device (字符串), 必需

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

        • allocation.devices.results.driver (字符串), 必需

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

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

        • allocation.devices.results.pool (字符串), 必需

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

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

        • allocation.devices.results.request (字符串), 必需

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

    • allocation.nodeSelector (NodeSelector)

      NodeSelector 定义了分配的资源在何处可用。如果未设置，则它们在任何地方都可用。

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

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

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

        必需。节点选择器术语的列表。这些术语是 OR 关系。

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

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

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

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

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

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

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

  • deallocationRequested (布尔值)

    指示要取消分配声明。当设置此项时，不得将新的使用者添加到 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 (字符串), 必需

      Name 是被引用资源的名称。

    • reservedFor.resource (字符串), 必需

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

    • reservedFor.uid (字符串), 必需

      UID 准确标识资源的一个实例。

    • reservedFor.apiGroup (字符串)

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

ResourceClaimList

ResourceClaimList 是声明的集合。

  • apiVersion: resource.k8s.io/v1alpha3

  • kind: ResourceClaimList

  • metadata (ListMeta)

    标准列表元数据

  • items ([]ResourceClaim), 必需

    Items 是资源声明的列表。

操作

get 读取指定的 ResourceClaim

HTTP 请求

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

参数

  • name (在路径中): 字符串, 必需

    ResourceClaim 的名称

  • namespace (在路径中): 字符串, 必需

    命名空间

  • pretty (在查询中): 字符串

    pretty

响应

200 (ResourceClaim): 确定

401: 未授权

get 读取指定 ResourceClaim 的状态

HTTP 请求

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

参数

  • name (在路径中): 字符串, 必需

    ResourceClaim 的名称

  • namespace (在路径中): 字符串, 必需

    命名空间

  • pretty (在查询中): 字符串

    pretty

响应

200 (ResourceClaim): 确定

401: 未授权

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

HTTP 请求

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

参数

响应

200 (ResourceClaimList): OK

401: 未授权

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

HTTP 请求

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

参数

响应

200 (ResourceClaimList): OK

401: 未授权

create 创建 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): 确定

201 (ResourceClaim): 已创建

202 (ResourceClaim): 已接受

401: 未授权

update 替换指定的 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): 确定

201 (ResourceClaim): 已创建

401: 未授权

update 替换指定 ResourceClaim 的状态

HTTP 请求

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

参数

响应

200 (ResourceClaim): 确定

201 (ResourceClaim): 已创建

401: 未授权

patch 部分更新指定的 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): 确定

201 (ResourceClaim): 已创建

401: 未授权

patch 部分更新指定 ResourceClaim 的状态

HTTP 请求

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

参数

响应

200 (ResourceClaim): 确定

201 (ResourceClaim): 已创建

401: 未授权

delete 删除 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): 确定

202 (ResourceClaim): 已接受

401: 未授权

deletecollection 删除 ResourceClaim 集合

HTTP 请求

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

参数

响应

200 (Status): OK

401: 未授权

此页面是自动生成的。

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

上次修改时间：2024 年 8 月 28 日 下午 6:01 PST：为 v1.31 更新生成的 API 参考 (8ba98c79c1)