ResourceClaim

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

apiVersion: resource.k8s.io/v1

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

ResourceClaim

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

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

  • apiVersion: resource.k8s.io/v1

  • kind: ResourceClaim

  • metadata (ObjectMeta)

    标准对象元数据

  • spec (ResourceClaimSpec)，必需

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

  • status (ResourceClaimStatus)

    Status 描述了声明是否已准备好使用以及已分配了什么。

ResourceClaimSpec

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

  • 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”），以及不同版本之间的转换。

          原始数据长度必须小于或等于 10 Ki。

          *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",
	},
}

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

      • devices.config.requests ([]string)

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

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

        对子请求的引用必须包含主请求的名称，并且可以使用 <主请求>/[<子请求>] 的格式包含子请求。如果只给出主请求，则配置适用于所有子请求。

    • devices.constraints ([]DeviceConstraint)

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

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

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

      • devices.constraints.distinctAttribute (string)

        DistinctAttribute 要求所有相关设备都具有此属性，并且其类型和值在这些设备中是唯一的。

        这与 MatchAttribute 的作用相反。

        此约束用于通过确保属性级别的差异化来避免将多个请求分配给同一设备。

        这对于资源请求必须由单独的物理设备满足的场景很有用。例如，容器请求两个网络接口，这些接口必须从两个不同的物理网卡分配。

      • devices.constraints.matchAttribute (string)

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

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

        必须包含域名限定符。

      • devices.constraints.requests ([]string)

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

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

        对子请求的引用必须包含主请求的名称，并且可以使用 <主请求>/[<子请求>] 的格式包含子请求。如果只给出主请求，则约束适用于所有子请求。

    • devices.requests ([]DeviceRequest)

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

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

      DeviceRequest 是对声明所需设备的请求。这通常是对单个资源（如设备）的请求，但也可以请求多个相同的设备。通过 FirstAvailable，还可以提供一个按优先级排序的请求列表。

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

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

        当 Exactly 字段设置时，使用 DeviceRequest 中的名称引用将唯一标识一个请求。当 FirstAvailable 字段设置时，对 DeviceRequest 名称的引用将匹配调度器选择的任何子请求。

        必须是 DNS 标签。

      • devices.requests.exactly (ExactDeviceRequest)

        Exactly 指定了单个请求的详细信息，该请求必须完全满足才能使请求得到满足。

        Exactly 或 FirstAvailable 必须设置一个。

        ExactDeviceRequest 是对一个或多个相同设备的请求。

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

          DeviceClassName 引用一个特定的 DeviceClass，该 DeviceClass 可以定义此请求将继承的附加配置和选择器。

          DeviceClassName 是必需的。

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

        • devices.requests.exactly.adminAccess (boolean)

          AdminAccess 表示这是一个对设备进行管理访问的声明。具有 AdminAccess 的声明预计用于设备的监控或其他管理服务。它们将忽略设备的所有普通声明，无论访问模式和任何资源分配如何。

          这是一个 Alpha 字段，需要启用 DRAAdminAccess 功能门控。如果此字段未设置或设置为 false，则禁用管理访问；否则启用。

        • devices.requests.exactly.allocationMode (string)

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

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

          • All：此请求针对池中所有匹配的设备。节点上至少需要存在一个设备才能成功分配。如果某些设备已被分配，则分配将失败，除非请求了 adminAccess。

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

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

        • devices.requests.exactly.capacity (CapacityRequirements)

          Capacity 定义了针对每个容量的资源要求。

          如果此字段未设置且设备支持多重分配，则将根据 requestPolicy 将默认值应用于每个容量。对于没有 requestPolicy 的容量，默认值为完整容量值。

          适用于每个设备分配。如果 Count > 1，如果满足要求的设备不足，则请求失败。如果 AllocationMode 设置为 All，如果存在其他匹配请求且具有此容量的设备，其值 >= 请求量，但无法分配给此请求，则请求失败。

          CapacityRequirements 定义了特定设备请求的容量要求。

          • devices.requests.exactly.capacity.requests (map[string]Quantity)

            Requests 表示对不同资源的单个设备资源请求，所有这些资源都必须由设备提供。

            此值用作设备可用容量的附加过滤条件。这在语义上等同于带有 `device.capacity[\<domain>].\<name>.compareTo(quantity(\<request quantity>)) >= 0` 的 CEL 选择器。例如，device.capacity['test-driver.cdi.k8s.io'].counters.compareTo(quantity('2')) >= 0。

            当定义了 requestPolicy 时，请求的数量会根据策略向上调整到最接近的有效值。如果请求的数量无法调整到有效值（因为它超出了 requestPolicy 允许的范围），则该设备被视为不符合分配条件。

            对于任何未明确请求的容量：- 如果未设置 requestPolicy，则默认消耗容量等于设备的全部容量（即，整个设备被声明）。

            • 如果设置了 requestPolicy，则默认消耗容量根据该策略确定。

            如果设备允许多重分配，则所有请求的总量不得超过容量值。消耗的容量（如果定义了 requestPolicy，可能会根据策略进行调整）记录在资源声明的 status.devices[*].consumedCapacity 字段中。

        • devices.requests.exactly.count (int64)

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

        • devices.requests.exactly.selectors ([]DeviceSelector)

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

          Selectors 定义了特定设备必须满足的条件，以便该设备被考虑用于此请求。所有选择器都必须满足才能考虑设备。

          DeviceSelector 必须且仅有一个字段被设置。

          • devices.requests.exactly.selectors.cel (CELDeviceSelector)

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

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

            • devices.requests.exactly.selectors.cel.expression (string)，必需

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

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

              • driver (字符串): 定义此设备的驱动程序名称。
              • attributes (map[string]object): 设备的属性，按前缀分组（例如 device.attributes["dra.example.com"] 评估为一个包含所有以 "dra.example.com" 为前缀的属性的对象）。
              • capacity (map[string]object): 设备的容量，按前缀分组。
              • allowMultipleAllocations (bool)：设备的 allowMultipleAllocations 属性（v1.34+ 启用 DRAConsumableCapacity 功能时）。

              示例：考虑一个驱动程序为 "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)

              表达式的长度必须小于或等于 10 Ki。评估成本也根据估计的逻辑步骤数受到限制。

        • devices.requests.exactly.tolerations ([]DeviceToleration)

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

          如果指定，则为请求的容忍度。

          需要 NoSchedule 的容忍度才能分配具有该效果的污点设备。NoExecute 亦然。

          此外，如果任何已分配设备在分配后被 NoExecute 污点污染且该效果未被容忍，则所有使用 ResourceClaim 的 Pod 都将被删除以驱逐它们。调度器将不允许新 Pod 在具有这些污点设备时保留该声明。一旦所有 Pod 被驱逐，该声明将被解除分配。

          容忍度的最大数量为 16。

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

          此 DeviceToleration 所附加的 ResourceClaim 容忍任何使用匹配运算符 匹配三元组 <key,value,effect> 的污点。

          • devices.requests.exactly.tolerations.effect (string)

            Effect 指示要匹配的污点效果。空表示匹配所有污点效果。如果指定，允许的值为 NoSchedule 和 NoExecute。

          • devices.requests.exactly.tolerations.key (string)

            Key 是容忍度适用的污点键。空表示匹配所有污点键。如果键为空，则 operator 必须是 Exists；这种组合表示匹配所有值和所有键。必须是标签名称。

          • devices.requests.exactly.tolerations.operator (string)

            Operator 表示键与值的关系。有效运算符是 Exists 和 Equal。默认为 Equal。Exists 等同于值的通配符，因此 ResourceClaim 可以容忍特定类别的所有污点。

          • devices.requests.exactly.tolerations.tolerationSeconds (int64)

            TolerationSeconds 表示容忍度（必须是 NoExecute 效果，否则此字段将被忽略）容忍污点的时间段。默认情况下，它未设置，这意味着永远容忍污点（不驱逐）。零和负值将被系统视为 0（立即驱逐）。如果大于零，则计算 Pod 需要被驱逐的时间为 <污点添加时间> + <容忍秒数>。

          • devices.requests.exactly.tolerations.value (string)

            Value 是容忍度匹配的污点值。如果 operator 是 Exists，则 value 必须为空，否则只是一个普通字符串。必须是标签值。

      • devices.requests.firstAvailable ([]DeviceSubRequest)

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

        FirstAvailable 包含子请求，调度器将从中选择一个。它会按照它们在此处列出的顺序尝试满足它们。因此，如果列表中有两条条目，调度器只有在确定第一条条目无法使用时才会检查第二条。

        DRA 尚未实现评分，因此调度器将选择满足声明中所有请求的第一组设备。如果要求可以在多个节点上满足，则其他调度功能将决定选择哪个节点。这意味着分配给声明的设备集可能不是集群可用的最佳设备集。评分将在以后实现。

        *DeviceSubRequest 描述了声明.spec.devices.requests[].firstAvailable 数组中提供的设备请求。每个通常是对单个资源（如设备）的请求，但也可以请求多个相同的设备。

        DeviceSubRequest 类似于 ExactDeviceRequest，但不公开 AdminAccess 字段，因为该字段仅在请求特定设备时才受支持。*

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

          DeviceClassName 引用一个特定的 DeviceClass，该 DeviceClass 可以定义此子请求将继承的附加配置和选择器。

          类是必需的。哪些类可用取决于集群。

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

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

          Name 可用于在约束列表或声明的配置列表中引用此子请求。引用必须使用 <主请求>/<子请求> 格式。

          必须是 DNS 标签。

        • devices.requests.firstAvailable.allocationMode (string)

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

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

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

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

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

        • devices.requests.firstAvailable.capacity (CapacityRequirements)

          Capacity 定义了针对每个容量的资源要求。

          如果此字段未设置且设备支持多重分配，则将根据 requestPolicy 将默认值应用于每个容量。对于没有 requestPolicy 的容量，默认值为完整容量值。

          适用于每个设备分配。如果 Count > 1，如果满足要求的设备不足，则请求失败。如果 AllocationMode 设置为 All，如果存在其他匹配请求且具有此容量的设备，其值 >= 请求量，但无法分配给此请求，则请求失败。

          CapacityRequirements 定义了特定设备请求的容量要求。

          • devices.requests.firstAvailable.capacity.requests (map[string]Quantity)

            Requests 表示对不同资源的单个设备资源请求，所有这些资源都必须由设备提供。

            此值用作设备可用容量的附加过滤条件。这在语义上等同于带有 `device.capacity[\<domain>].\<name>.compareTo(quantity(\<request quantity>)) >= 0` 的 CEL 选择器。例如，device.capacity['test-driver.cdi.k8s.io'].counters.compareTo(quantity('2')) >= 0。

            当定义了 requestPolicy 时，请求的数量会根据策略向上调整到最接近的有效值。如果请求的数量无法调整到有效值（因为它超出了 requestPolicy 允许的范围），则该设备被视为不符合分配条件。

            对于任何未明确请求的容量：- 如果未设置 requestPolicy，则默认消耗容量等于设备的全部容量（即，整个设备被声明）。

            • 如果设置了 requestPolicy，则默认消耗容量根据该策略确定。

            如果设备允许多重分配，则所有请求的总量不得超过容量值。消耗的容量（如果定义了 requestPolicy，可能会根据策略进行调整）记录在资源声明的 status.devices[*].consumedCapacity 字段中。

        • devices.requests.firstAvailable.count (int64)

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

        • devices.requests.firstAvailable.selectors ([]DeviceSelector)

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

          选择器定义了特定设备必须满足的条件，以便该设备被考虑用于此子请求。所有选择器都必须满足才能考虑设备。

          DeviceSelector 必须且仅有一个字段被设置。

          • devices.requests.firstAvailable.selectors.cel (CELDeviceSelector)

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

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

            • devices.requests.firstAvailable.selectors.cel.expression (string)，必需

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

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

              • driver (字符串): 定义此设备的驱动程序名称。
              • attributes (map[string]object): 设备的属性，按前缀分组（例如 device.attributes["dra.example.com"] 评估为一个包含所有以 "dra.example.com" 为前缀的属性的对象）。
              • capacity (map[string]object): 设备的容量，按前缀分组。
              • allowMultipleAllocations (bool)：设备的 allowMultipleAllocations 属性（v1.34+ 启用 DRAConsumableCapacity 功能时）。

              示例：考虑一个驱动程序为 "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)

              表达式的长度必须小于或等于 10 Ki。评估成本也根据估计的逻辑步骤数受到限制。

        • devices.requests.firstAvailable.tolerations ([]DeviceToleration)

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

          如果指定，则为请求的容忍度。

          需要 NoSchedule 的容忍度才能分配具有该效果的污点设备。NoExecute 亦然。

          此外，如果任何已分配设备在分配后被 NoExecute 污点污染且该效果未被容忍，则所有使用 ResourceClaim 的 Pod 都将被删除以驱逐它们。调度器将不允许新 Pod 在具有这些污点设备时保留该声明。一旦所有 Pod 被驱逐，该声明将被解除分配。

          容忍度的最大数量为 16。

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

          此 DeviceToleration 所附加的 ResourceClaim 容忍任何使用匹配运算符 匹配三元组 <key,value,effect> 的污点。

          • devices.requests.firstAvailable.tolerations.effect (string)

            Effect 指示要匹配的污点效果。空表示匹配所有污点效果。如果指定，允许的值为 NoSchedule 和 NoExecute。

          • devices.requests.firstAvailable.tolerations.key (string)

            Key 是容忍度适用的污点键。空表示匹配所有污点键。如果键为空，则 operator 必须是 Exists；这种组合表示匹配所有值和所有键。必须是标签名称。

          • devices.requests.firstAvailable.tolerations.operator (string)

            Operator 表示键与值的关系。有效运算符是 Exists 和 Equal。默认为 Equal。Exists 等同于值的通配符，因此 ResourceClaim 可以容忍特定类别的所有污点。

          • devices.requests.firstAvailable.tolerations.tolerationSeconds (int64)

            TolerationSeconds 表示容忍度（必须是 NoExecute 效果，否则此字段将被忽略）容忍污点的时间段。默认情况下，它未设置，这意味着永远容忍污点（不驱逐）。零和负值将被系统视为 0（立即驱逐）。如果大于零，则计算 Pod 需要被驱逐的时间为 <污点添加时间> + <容忍秒数>。

          • devices.requests.firstAvailable.tolerations.value (string)

            Value 是容忍度匹配的污点值。如果 operator 是 Exists，则 value 必须为空，否则只是一个普通字符串。必须是标签值。

ResourceClaimStatus

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

  • allocation (AllocationResult)

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

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

    • allocation.allocationTimestamp (Time)

      AllocationTimestamp 存储资源分配的时间。此字段不保证设置，在这种情况下，该时间是未知的。

      这是一个 Alpha 字段，需要启用 DRADeviceBindingConditions 和 DRAResourceClaimDeviceStatus 功能门控。

      Time 是 time.Time 的一个包装器，支持正确地编组到 YAML 和 JSON。提供了 time 包提供的许多工厂方法的包装器。

    • 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”），以及不同版本之间的转换。

            原始数据长度必须小于或等于 10 Ki。

            *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", }, }

            那么会发生什么？首先，Decode 使用 json 或 yaml 将序列化数据反序列化到外部 MyAPIObject 中。这导致原始 JSON 被存储，但未解包。下一步是复制（使用 pkg/conversion）到内部结构中。运行时包的 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 是声明中导致此设备被分配的请求名称。如果它引用 DeviceRequest 上 firstAvailable 列表中的子请求，则此字段必须包含主请求和子请求的名称，格式为 <主请求>/<子请求>。

          每个请求可能已分配了多个设备。

        • allocation.devices.results.adminAccess (boolean)

          AdminAccess 表示此设备已分配用于管理访问。有关模式的定义，请参阅相应的请求字段。

          这是一个 Alpha 字段，需要启用 DRAAdminAccess 功能门控。如果此字段未设置或设置为 false，则禁用管理访问；否则启用。

        • allocation.devices.results.bindingConditions ([]string)

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

          BindingConditions 包含分配时相应 ResourceSlice 中的 BindingConditions 的副本。

          这是一个 Alpha 字段，需要启用 DRADeviceBindingConditions 和 DRAResourceClaimDeviceStatus 功能门控。

        • allocation.devices.results.bindingFailureConditions ([]string)

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

          BindingFailureConditions 包含分配时相应 ResourceSlice 中的 BindingFailureConditions 的副本。

          这是一个 Alpha 字段，需要启用 DRADeviceBindingConditions 和 DRAResourceClaimDeviceStatus 功能门控。

        • allocation.devices.results.consumedCapacity (map[string]Quantity)

          ConsumedCapacity 跟踪每个设备作为声明请求一部分所消耗的容量。消耗量可能与请求量不同：如果适用（即，不能小于请求量），它会根据设备的 requestPolicy 四舍五入到最接近的有效值。

          每个设备的总消耗容量不得超过 DeviceCapacity 的 Value。

          此字段仅填充允许多重分配的设备。所有容量条目都包括在内，即使消耗量为零。

        • allocation.devices.results.shareID (string)

          ShareID 唯一标识设备的单个分配份额，当设备支持多个同时分配时使用。它作为附加的映射键来区分同一设备的同时份额。

        • allocation.devices.results.tolerations ([]DeviceToleration)

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

          设备分配时请求中指定的所有容忍度的副本。

          容忍度的最大数量为 16。

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

          此 DeviceToleration 所附加的 ResourceClaim 容忍任何使用匹配运算符 匹配三元组 <key,value,effect> 的污点。

          • allocation.devices.results.tolerations.effect (string)

            Effect 指示要匹配的污点效果。空表示匹配所有污点效果。如果指定，允许的值为 NoSchedule 和 NoExecute。

          • allocation.devices.results.tolerations.key (string)

            Key 是容忍度适用的污点键。空表示匹配所有污点键。如果键为空，则 operator 必须是 Exists；这种组合表示匹配所有值和所有键。必须是标签名称。

          • allocation.devices.results.tolerations.operator (string)

            Operator 表示键与值的关系。有效运算符是 Exists 和 Equal。默认为 Equal。Exists 等同于值的通配符，因此 ResourceClaim 可以容忍特定类别的所有污点。

          • allocation.devices.results.tolerations.tolerationSeconds (int64)

            TolerationSeconds 表示容忍度（必须是 NoExecute 效果，否则此字段将被忽略）容忍污点的时间段。默认情况下，它未设置，这意味着永远容忍污点（不驱逐）。零和负值将被系统视为 0（立即驱逐）。如果大于零，则计算 Pod 需要被驱逐的时间为 <污点添加时间> + <容忍秒数>。

          • allocation.devices.results.tolerations.value (string)

            Value 是容忍度匹配的污点值。如果 operator 是 Exists，则 value 必须为空，否则只是一个普通字符串。必须是标签值。

    • allocation.nodeSelector (NodeSelector)

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

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

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

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

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

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

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

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

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

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

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

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

  • devices ([]AllocatedDeviceStatus)

    Map：在合并过程中，将保留键 `driver, device, pool, shareID` 的唯一值

    Devices 包含此声明分配的每个设备的状态，由驱动程序报告。这可能包括驱动程序特定信息。条目由各自的驱动程序拥有。

    *AllocatedDeviceStatus 包含已分配设备的状态，如果驱动程序选择报告的话。这可能包括驱动程序特定信息。

    Driver、Pool、Device 和 ShareID 的组合必须与 Status.Allocation.Devices 中的相应键匹配。*

    • devices.device (string)，必需

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

    • devices.driver (string)，必需

      Driver 指定 DRA 驱动程序的名称，当节点上需要声明时，将调用其 kubelet 插件来处理分配。

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

    • devices.pool (string)，必需

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

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

    • devices.conditions ([]Condition)

      映射：合并时将保留键类型上的唯一值

      Conditions 包含设备状态的最新观察结果。如果设备已根据类和声明配置引用进行了配置，则 `Ready` 条件应为 True。

      不能包含超过 8 个条目。

      Condition 包含此 API 资源当前状态的一个方面的详细信息。

      • devices.conditions.lastTransitionTime (Time)，必需

        lastTransitionTime 是条件上次从一种状态转换到另一种状态的时间。这应该是底层条件发生变化的时间。如果不知道，则使用 API 字段发生变化的时间是可接受的。

        Time 是 time.Time 的一个包装器，支持正确地编组到 YAML 和 JSON。提供了 time 包提供的许多工厂方法的包装器。

      • devices.conditions.message (string)，必需

        message 是一个人类可读的消息，指示有关转换的详细信息。这可能是一个空字符串。

      • devices.conditions.reason (string)，必需

        reason 包含一个程序化标识符，指示条件上次转换的原因。特定条件类型的生产者可以为此字段定义预期值和含义，以及这些值是否被视为有保证的 API。该值应该是一个 CamelCase 字符串。此字段不能为空。

      • devices.conditions.status (string)，必需

        条件状态，True、False、Unknown 之一。

      • devices.conditions.type (string)，必需

        条件类型，CamelCase 或 foo.example.com/CamelCase。

      • devices.conditions.observedGeneration (int64)

        observedGeneration 表示条件所基于的 .metadata.generation。例如，如果 .metadata.generation 当前为 12，但 .status.conditions[x].observedGeneration 为 9，则条件与实例的当前状态不一致。

    • devices.data (RawExtension)

      Data 包含任意驱动程序特定数据。

      原始数据长度必须小于或等于 10 Ki。

      *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",
	},
}

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

    • devices.networkData (NetworkDeviceData)

      NetworkData 包含设备特定的网络相关信息。

      NetworkDeviceData 提供了分配设备的网络相关详细信息。此信息可以由驱动程序或其他组件填充，以在网络环境中配置或标识设备。

      • devices.networkData.hardwareAddress (string)

        HardwareAddress 表示设备网络接口的硬件地址（例如 MAC 地址）。

        长度不得超过 128 个字符。

      • devices.networkData.interfaceName (string)

        InterfaceName 指定与分配设备关联的网络接口名称。这可能是 Pod 中正在配置的物理或虚拟网络接口的名称。

        长度不得超过 256 个字符。

      • devices.networkData.ips ([]string)

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

        IPs 列出了分配给设备网络接口的网络地址。这可以包括 IPv4 和 IPv6 地址。IPs 采用 CIDR 表示法，包括地址和关联的子网掩码。例如："192.0.2.5/24" 用于 IPv4，"2001:db8::5/64" 用于 IPv6。

    • devices.shareID (string)

      ShareID 唯一标识设备的单个分配份额。

  • reservedFor ([]ResourceClaimConsumerReference)

    补丁策略：在键 `uid` 上合并

    Map：在合并过程中，将保留键 uid 的唯一值

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

    在具有多个调度器实例的集群中，两个 Pod 可能会被不同的调度器同时调度。当它们引用已达到最大消费者数量的相同 ResourceClaim 时，只能调度一个 Pod。

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

    最多可以有 256 个这样的保留。将来可能会增加，但不会减少。

    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/v1

  • kind: ResourceClaimList

  • metadata (ListMeta)

    标准列表元数据

  • items ([]ResourceClaim)，必需

    Items 是资源声明的列表。

操作

get 读取指定的 ResourceClaim

HTTP 请求

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

参数

  • name (在路径中): string，必填

    ResourceClaim 的名称

  • namespace (在路径中): string，必填

    命名空间

  • pretty (在查询中): string

    pretty

响应

200 (ResourceClaim): OK

401: 未授权

get 读取指定 ResourceClaim 的状态

HTTP 请求

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

参数

  • name (在路径中): string，必填

    ResourceClaim 的名称

  • namespace (在路径中): string，必填

    命名空间

  • pretty (在查询中): string

    pretty

响应

200 (ResourceClaim): OK

401: 未授权

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

HTTP 请求

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

参数

响应

200 (ResourceClaimList): OK

401: 未授权

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

HTTP 请求

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

参数

响应

200 (ResourceClaimList): OK

401: 未授权

create 创建 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

202 (ResourceClaim): 已接受

401: 未授权

update 替换指定的 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

401: 未授权

update 替换指定 ResourceClaim 的状态

HTTP 请求

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

参数

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

401: 未授权

patch 部分更新指定的 ResourceClaim

HTTP 请求

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

参数

  • name (在路径中): string，必填

    ResourceClaim 的名称

  • namespace (在路径中): string，必填

    命名空间

  • body: Patch，必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • force (在查询中): boolean

    force

  • pretty (在查询中): string

    pretty

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

401: 未授权

patch 部分更新指定 ResourceClaim 的状态

HTTP 请求

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

参数

  • name (在路径中): string，必填

    ResourceClaim 的名称

  • namespace (在路径中): string，必填

    命名空间

  • body: Patch，必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • force (在查询中): boolean

    force

  • pretty (在查询中): string

    pretty

响应

200 (ResourceClaim): OK

201 (ResourceClaim): 已创建

401: 未授权

delete 删除 ResourceClaim

HTTP 请求

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

参数

响应

200 (ResourceClaim): OK

202 (ResourceClaim): 已接受

401: 未授权

deletecollection 删除 ResourceClaim 集合

HTTP 请求

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

参数

响应

200 (Status): OK

401: 未授权

本页面是自动生成的。

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

上次修改时间：2025 年 9 月 4 日 下午 3:37 PST：更新 v1.34 的 API 资源参考 (3e10e8c195)