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)

    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)

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

      这些约束必须由为申领分配的设备集合所满足。

      除了 requests 之外，DeviceConstraint 还必须有且仅有一个字段被设置。

      • 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 供用户引用。

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

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

        必须是 DNS 标签。

      • devices.requests.adminAccess (boolean)

        adminAccess 表示这是对设备的管理访问权限的申领请求。 使用 adminAccess 的申领请求预期用于设备的监控或其他管理服务。 就访问模式和资源分配而言，它们会忽略对设备的所有普通申领。

      • devices.requests.allocationMode (string)

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

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

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

        如果 allocationMode 未被指定，则默认模式为 ExactCount。 如果模式为 ExactCount 而 count 未被指定，则默认值为 1。 其他任何请求必须指定此字段。

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

      • devices.requests.count (int64)

        count 仅在计数模式为 "ExactCount" 时使用。必须大于零。 如果 allocationMode 为 ExactCount 而此字段未被指定，则默认值为 1。

      • devices.requests.selectors ([]DeviceSelector)

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

        selectors 定义特定设备必须满足的条件，满足条件的设备被视为此请求的候选者。 所有选择算符必须同时被满足才会考虑某个设备。

        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)：设备的容量，按前缀分组。

            示例：考虑一个驱动为 "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 字段可用于检查特定驱动，既可以作为高层次的前提条件（即你只想考虑来自此驱动的设备）， 也可以作为考虑来自不同驱动的设备的多子句表达式的一部分。

            attribute 中每个元素的值类型由设备定义，编写这些表达式的用户必须查阅其特定驱动的文档。 capacity 中元素的值类型为 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 定义在哪儿可以使用分配的资源。如果不设置，则分配的资源在任何地方都可用。

      节点选择算符表示在一组节点上一个或多个标签查询结果的并集； 也就是说，它表示由节点选择算符条件表示的选择算符的逻辑或计算结果。

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

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

        必需。节点选择算符条件的列表。这些条件以逻辑与进行计算。

        一个 null 或空的节点选择算符条件不会与任何对象匹配。这些要求会按逻辑与的关系来计算。 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/v1alpha3

  • kind: ResourceClaimList

  • metadata (ListMeta)

    标准的列表元数据。

  • items ([]ResourceClaim)，必需

    items 是资源申领的列表。

操作

get 读取指定的 ResourceClaim

HTTP 请求

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

参数

  • name（路径参数）：string，必需

    ResourceClaim 的名称。

  • namespace（路径参数）：string，必需

    namespace

  • pretty（查询参数）：string

    pretty

响应

200 (ResourceClaim): OK

401: Unauthorized

get 读取指定 ResourceClaim 的状态

HTTP 请求

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

参数

  • name（路径参数）：string，必需

    ResourceClaim 的名称。

  • namespace（路径参数）：string，必需

    namespace

  • pretty（查询参数）：string

    pretty

响应

200 (ResourceClaim): OK

401: Unauthorized

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

HTTP 请求

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

参数

响应

200 (ResourceClaimList): OK

401: Unauthorized

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

HTTP 请求

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

参数

响应

200 (ResourceClaimList): OK

401: Unauthorized

create 创建 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): OK

201 (ResourceClaim): Created

202 (ResourceClaim): Accepted

401: Unauthorized

update 替换指定的 ResourceClaim

HTTP 请求

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

参数

  • name（路径参数）：string，必需

    ResourceClaim 的名称。

  • namespace（路径参数）：string，必需

    namespace

  • body: ResourceClaim，必需

  • dryRun（查询参数）：string

    dryRun

  • fieldManager（查询参数）：string

    fieldManager

  • fieldValidation（查询参数）：string

    fieldValidation

  • pretty（查询参数）：string

    pretty

响应

200 (ResourceClaim): OK

201 (ResourceClaim): Created

401: Unauthorized

update 替换指定 ResourceClaim 的状态

HTTP 请求

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

参数

  • name（路径参数）：string，必需

    ResourceClaim 的名称。

  • namespace（路径参数）：string，必需

    namespace

  • body: ResourceClaim，必需

  • dryRun（查询参数）：string

    dryRun

  • fieldManager（查询参数）：string

    fieldManager

  • fieldValidation（查询参数）：string

    fieldValidation

  • pretty（查询参数）：string

    pretty

响应

200 (ResourceClaim): OK

201 (ResourceClaim): Created

401: Unauthorized

patch 部分更新指定的 ResourceClaim

HTTP 请求

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

参数

  • name（路径参数）：string，必需

    ResourceClaim 的名称。

  • namespace（路径参数）：string，必需

    namespace

  • body: Patch，必需

  • dryRun（查询参数）：string

    dryRun

  • fieldManager（查询参数）：string

    fieldManager

  • fieldValidation（查询参数）：string

    fieldValidation

  • force（查询参数）：boolean

    force

  • pretty（查询参数）：string

    pretty

响应

200 (ResourceClaim): OK

201 (ResourceClaim): Created

401: Unauthorized

patch 部分更新指定 ResourceClaim 的状态

HTTP 请求

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

参数

  • name（路径参数）：string，必需

    ResourceClaim 的名称。

  • namespace（路径参数）：string，必需

    namespace

  • body: Patch，必需

  • dryRun（查询参数）：string

    dryRun

  • fieldManager（查询参数）：string

    fieldManager

  • fieldValidation（查询参数）：string

    fieldValidation

  • force（查询参数）：boolean

    force

  • pretty（查询参数）：string

    pretty

响应

200 (ResourceClaim): OK

201 (ResourceClaim): Created

401: Unauthorized

delete 删除 ResourceClaim

HTTP 请求

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

参数

  • name（路径参数）：string，必需

    ResourceClaim 的名称。

  • namespace（路径参数）：string，必需

    namespace

  • body: DeleteOptions

  • dryRun（查询参数）：string

    dryRun

  • gracePeriodSeconds（查询参数）：integer

    gracePeriodSeconds

  • pretty（查询参数）：string

    pretty

  • propagationPolicy（查询参数）：string

    propagationPolicy

响应

200 (ResourceClaim): OK

202 (ResourceClaim): Accepted

401: Unauthorized

deletecollection 删除 ResourceClaim 的集合

HTTP 请求

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

参数

响应

200 (Status): OK

401: Unauthorized

最后修改 September 04, 2024 at 10:26 AM PST: [zh] Add workload-resources/resource-claim-v1alpha3.md (f91dc17fcc)