Kubernetes Python 客户端 V1beta2ResourceClaim 模型详解：Dynamic Resource Allocation 资源声明的完整 API 参考

后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载导读本文面向使用官方 Kubernetes Python 客户端本项目仓库gh_mirrors/python1/python的开发者系统讲解V1beta2ResourceClaim模型——它是 Kubernetes 动态资源分配Dynamic Resource Allocation简称 DRA体系中描述工作负载需要访问集群中哪些资源的核心对象。读完本文你将掌握该模型的字段结构、JSON 序列化规则、与ResourceV1beta2Api的联动方式以及如何在同步kubernetes.client与异步kubernetes.aio.client两种客户端形态下构造并提交一个真实的 ResourceClaim。本文以 doc/source/kubernetes.aio.client.models.v1beta2_resource_claim.rst 自动生成的模块文档为入口结合 kubernetes/aio/client/models/v1beta2_resource_claim.py 等源码进行纵深解读。一、模块文档与模型定位1.1 文档入口与 automodule 机制关联文档 doc/source/kubernetes.aio.client.models.v1beta2_resource_claim.rst 是典型的 Sphinxautomodule自动 API 参考页.. automodule:: kubernetes.aio.client.models.v1beta2_resource_claim :members: :show-inheritance: :undoc-members:它并不手工罗列成员而是指示 Sphinx 从kubernetes.aio.client.models.v1beta2_resource_claim模块中提取全部公开成员:members:、继承关系:show-inheritance:以及未写文档字符串的成员:undoc-members:最终渲染出V1beta2ResourceClaim类的完整参考。也就是说本文讲述的真实文档内容就是该模型类的 docstring 与全部公开 API。1.2 模型在 DRA 架构中的位置从源码 docstring 与 OpenAPI 定义scripts/swagger.json中的v1beta2.ResourceClaim可知ResourceClaim 描述了工作负载对集群内资源的访问请求。例如若某个工作负载需要具有特定属性的加速器设备accelerator device该请求正是通过 ResourceClaim 表达的status段记录了该请求是否已被满足以及具体分配了哪些资源。两个关键前提源码与 swagger 双重确认见 kubernetes/aio/client/models/v1beta2_resource_claim.py这是一个alpha 级类型需要启用DynamicResourceAllocationfeature gate生成的 OpenAPI 文档版本为release-1.37见文件头注释。模型类继承自pydantic.BaseModel采用 Pydantic v2 校验体系配套生成类属性openapi_types字段到类型的映射与attribute_mapPython 属性名到 JSON 线上名映射并实现了to_dict/from_dict/to_json/from_json等序列化方法。完整的同步版本位于 kubernetes/client/models/v1beta2_resource_claim.py二者内容一致分别服务于kubernetes.client与kubernetes.aio.client两套包。二、字段结构全景V1beta2ResourceClaim共声明 5 个字段对应__properties [apiVersion, kind, metadata, spec, status]下表汇总了字段、类型、JSON 线上名与说明字段Python类型JSON 线上名说明api_versionOptional[str]apiVersion对象的版本化 schema 标识服务端应将已识别的 schema 转换为最新的内部值并可能拒绝未识别的值kindOptional[str]kind对象所代表的 REST 资源类型字符串CamelCase不可更新metadataOptional[V1ObjectMeta]metadata标准对象元数据specOptional[V1beta2ResourceClaimSpec]spec描述请求什么资源以及如何配置该字段不可变immutablestatusOptional[V1beta2ResourceClaimStatus]status描述声明是否已就绪可用以及已分配了什么资源对应实现位于 kubernetes/aio/client/models/v1beta2_resource_claim.py其中openapi_types与attribute_map完整给出openapi_types: ClassVar[Dict[str, str]] { api_version: str, kind: str, metadata: V1ObjectMeta, spec: V1beta2ResourceClaimSpec, status: V1beta2ResourceClaimStatus } attribute_map: ClassVar[Dict[str, str]] { api_version: apiVersion, kind: kind, metadata: metadata, spec: spec, status: status }2.1 specV1beta2ResourceClaimSpeckubernetes/aio/client/models/v1beta2_resource_claim_spec.py 定义的V1beta2ResourceClaimSpec只有一个字段devices: Optional[V1beta2DeviceClaim]JSON 线上名同为devices含义为如何请求设备。也就是说v1beta2 的 ResourceClaim 声明内容全部收敛在DeviceClaim上。V1beta2DeviceClaim见 kubernetes/aio/client/models/v1beta2_device_claim.py包含三个列表字段字段类型说明configList[V1beta2DeviceClaimConfiguration]为多个潜在 driver 提供的配置在分配声明时被忽略constraintsList[V1beta2DeviceConstraint]必须被分配给该声明的设备集合整体满足的约束requestsList[V1beta2DeviceRequest]对独立设备的逐个请求必须全部被满足为空则无需分配任何东西其中V1beta2DeviceConstraintv1beta2_device_constraint.py必须恰好设置requests之外的其中一个字段match_attribute要求所有设备都具有该属性且类型与值一致例如dra.example.com/numa可确保设备处于同一 NUMA 节点属性名必须带域名限定符distinct_attribute与match_attribute相反要求所有设备在该属性上互不相同例如为两个网络接口分配来自不同物理 NIC 的设备requests约束所作用的请求名列表支持main request/[subrequest]格式。而V1beta2DeviceRequestv1beta2_device_request.py则要求必须提供nameDNS label可在pod.spec.containers[].resources.claims中引用并通过互斥的两种方式之一声明所需设备exactly: V1beta2ExactDeviceRequest请求一个或多个完全相同的设备first_available: List[V1beta2DeviceSubRequest]按优先级列出多个候选子请求调度器按列表顺序尝试第一个可用者胜出DRA 当前尚未实现打分scoring。V1beta2ExactDeviceRequestv1beta2_exact_device_request.py的字段要点device_class_name必填引用某个 DeviceClass可继承其额外的配置与选择器allocation_mode可选ExactCount默认或AllExactCount下未指定count时默认 1count仅用于ExactCount模式必须大于 0selectors设备候选的过滤条件所有选择器必须同时满足tolerations最多 16 条用于容忍设备的 taint需启用DRADeviceTaintsgatebetaadmin_access管理性访问声明需启用DRAAdminAccessgatealphaderived_attributes通过 CEL 表达式计算的虚拟属性最多 32 个需启用DRADerivedAttributesgatealpha。V1beta2DeviceSubRequestv1beta2_device_sub_request.py与ExactDeviceRequest类似但不暴露adminAccess字段且额外要求name引用格式main request/subrequest。2.2 statusV1beta2ResourceClaimStatuskubernetes/aio/client/models/v1beta2_resource_claim_status.py 定义了三个字段字段Python类型JSON 线上名说明allocationOptional[V1beta2AllocationResult]allocation声明被成功分配后由控制器写入devicesList[V1beta2AllocatedDeviceStatus]devicesdriver 报告的每个已分配设备的状态可包含 driver 专属信息reserved_forList[V1beta2ResourceClaimConsumerReference]reservedFor当前允许使用该声明的实体最多 256 条预留值得关注的是 swagger 定义scripts/swagger.json中v1beta2.ResourceClaimStatus补充的两种 OpenAPI 元数据devices为x-kubernetes-list-type: map以driver、device、pool、shareID为 map 键reservedFor同样为 map 列表以uid为键并声明x-kubernetes-patch-merge-key: uid与x-kubernetes-patch-strategy: merge即服务端支持按uid合并式 PATCH。V1beta2AllocatedDeviceStatusv1beta2_allocated_device_status.py包含conditions最多 8 条V1Condition设备就绪时Ready条件应为 True、datadriver 自定义数据原始长度 ≤ 10 Ki、device、driver、pool三者共同构成driver/pool/device标识以及可选的shareID、networkData。V1beta2ResourceClaimConsumerReferencev1beta2_resource_claim_consumer_reference.py则用apiGroup、name、resource、uid四个字段精确定位一个消费者必须与 ResourceClaim 处于同一 namespace。V1beta2AllocationResultv1beta2_allocation_result.py记录分配结果allocationTimestamp资源分配时间beta需启用DRADeviceBindingConditions与DRAResourceClaimDeviceStatusgate、devicesV1beta2DeviceAllocationResult以及nodeSelector限定资源所在节点。三、字段名的驼峰转换validation_alias 与序列化机制与早期python-legacy生成器不同本仓库的模型以 Pydantic v2 为基础对线上名wire name采用驼峰、Python 属性名采用下划线命名。例如api_version↔apiVersionreserved_for↔reservedForfirst_available↔firstAvailabledevice_class_name↔deviceClassName这在源码中以validation_aliasAliasChoices(apiVersion, api_version)与serialization_aliasapiVersion成对出现见 v1beta2_resource_claim.py。__preprocess_input_names负责在反序列化时把下划线键名映射为驼峰键名见 v1beta2_resource_claim_status.py因此构造对象时两种写法均可V1beta2ResourceClaim(api_version...)或V1beta2ResourceClaim(apiVersion...)序列化到 JSON 时to_json()/to_dict(serializeTrue)一律输出驼峰线上名与 Kubernetes API 服务器要求的 JSON 完全一致反序列化时from_dict()/from_json()对 API 服务器返回的驼峰 JSON 同样可正确处理。模型配置model_config同时开启了validate_by_nameTrue、validate_by_aliasTrue、validate_assignmentTrue并将extra设为forbid未知字段会触发校验错误protected_namespaces()允许字段名以model_等保留前缀开头见 v1beta2_resource_claim.py。四、CRUD 操作与 ResourceV1beta2Api 联动V1beta2ResourceClaim对象本身只是数据模型真正提交给集群需通过ResourceV1beta2Api异步版类位于 kubernetes/aio/client/api/resource_v1beta2_api.py。对应 REST 端点已在scripts/swagger.json中定义POST /apis/resource.k8s.io/v1beta2/namespaces/{namespace}/resourceclaimsDELETE /apis/resource.k8s.io/v1beta2/namespaces/{namespace}/resourceclaims/{name}GET /apis/resource.k8s.io/v1beta2/namespaces/{namespace}/resourceclaimsGET /apis/resource.k8s.io/v1beta2/resourceclaims跨 namespace 列举4.1 异步创建create_namespaced_resource_claim核心方法签名见 resource_v1beta2_api.pyasync def create_namespaced_resource_claim( self, namespace: Annotated[StrictStr, ...], body: V1beta2ResourceClaim, pretty: Optional[str] None, dry_run: Optional[str] None, field_manager: Optional[str] None, field_validation: Optional[str] None, ... ) - V1beta2ResourceClaim:参数说明namespace对象所在命名空间必填bodyV1beta2ResourceClaim实例必填请求成功返回 200/201/202 与新建的对象prettytrue时输出美化 JSONdry_runAll表示执行所有 dry-run 阶段但不持久化field_manager关联的 fieldManager 名称≤ 128 个可打印字符field_validationIgnore丢弃未知字段v1.23 之前默认、Warn返回警告头v1.23 默认、Strict遇到未知/重复字段直接报 BadRequest。4.2 完整的异步创建示例import asyncio from kubernetes import config from kubernetes.aio import config as aio_config from kubernetes.aio.client import ApiClient from kubernetes.aio.client.api import ResourceV1beta2Api from kubernetes.aio.client.models import ( V1ObjectMeta, V1beta2DeviceClaim, V1beta2DeviceRequest, V1beta2ExactDeviceRequest, V1beta2ResourceClaim, V1beta2ResourceClaimSpec, ) async def main(): # 使用集群外 kubeconfig也可改用 load_incluster_config await aio_config.load_kube_config() async with ApiClient() as client: api ResourceV1beta2Api(client) claim V1beta2ResourceClaim( api_versionresource.k8s.io/v1beta2, kindResourceClaim, metadataV1ObjectMeta(namegpu-claim, namespacedefault), specV1beta2ResourceClaimSpec( devicesV1beta2DeviceClaim( requests[ V1beta2DeviceRequest( namegpu, exactlyV1beta2ExactDeviceRequest( device_class_namegpu.example.com, count1, allocation_modeExactCount, ), ) ] ) ), ) created await api.create_namespaced_resource_claim( namespacedefault, bodyclaim, field_managermy-app ) print(created.to_dict()) asyncio.run(main())该示例使用了 examples_asyncio/ 目录所体现的async with ApiClient()资源管理惯例以及kubernetes.aio.config的异步配置加载方式见 examples_asyncio/list_pods.py。4.3 同步形态若使用同步客户端将导入路径换成kubernetes.client即可类与方法的签名保持一致from kubernetes import client, config config.load_kube_config() api client.ResourceV1beta2Api() claim client.V1beta2ResourceClaim( api_versionresource.k8s.io/v1beta2, kindResourceClaim, metadataclient.V1ObjectMeta(namegpu-claim, namespacedefault), specclient.V1beta2ResourceClaimSpec( devicesclient.V1beta2DeviceClaim( requests[ client.V1beta2DeviceRequest( namegpu, exactlyclient.V1beta2ExactDeviceRequest( device_class_namegpu.example.com, count1, allocation_modeExactCount, ), ) ] ) ), ) created api.create_namespaced_resource_claim(namespacedefault, bodyclaim)两种客户端的完整方法列表可见 kubernetes/README.mdResourceV1beta2Api一节包含 create/delete/list/patch/read/replace 以及 resourceclaimtemplate 相关方法。五、对象序列化与反序列化实践V1beta2ResourceClaim继承自 PydanticBaseModel并覆盖了序列化接口常用方法方法说明to_dict(serializeFalse)返回 Python 字典键为 Python 属性名下划线风格to_dict(serializeTrue)/to_json()输出线上格式键为驼峰 JSON 名如apiVersion、reservedForfrom_dict(obj)从字典构建实例自动处理驼峰/下划线键名映射from_json(json_str)从 JSON 字符串构建实例to_str()/__repr__打印友好的多行字符串表示便于调试例如claim V1beta2ResourceClaim.from_dict({ apiVersion: resource.k8s.io/v1beta2, kind: ResourceClaim, metadata: {name: gpu-claim, namespace: default}, spec: {devices: {requests: [...]}}, }) print(claim.to_json()) # 输出驼峰 JSON可直接用于 API 请求体源码中的__openapi_generator_modern_projection见 v1beta2_resource_claim.py保证嵌套模型metadata、spec、status也通过各自的to_dict()递归转换从而得到与 API 服务器一致的完整线上 JSON。六、使用前提与限制综合源码 docstring 与 swagger 定义使用V1beta2ResourceClaim需注意以下前提与限制feature gate类型本身为 alpha需在集群开启DynamicResourceAllocation部分子字段还依赖额外 gate——DRAAdminAccessalpha、DRADerivedAttributesalpha、DRADeviceTaintsbeta、DRADeviceBindingConditions/DRAResourceClaimDeviceStatusbeta影响allocationTimestamp、DRAListTypeAttributes影响约束属性的集合语义比较。不可变性spec不可更新swagger 明确标注 The spec is immutable变更声明需重建对象。配额与上限status.reservedFor最多 256 条预留ExactDeviceRequest.tolerations最多 16 条AllocatedDeviceStatus.conditions最多 8 条data原始长度 ≤ 10 KiBderived_attributes最多 32 个。name 约束DeviceRequest.name、DeviceSubRequest.name、AllocatedDeviceStatus.device必须为 DNS labeldriver必须为 DNS 子域且建议以厂商拥有的域名结尾。并发调度语义多调度器实例并发为同一 claim 预留消费者时仅最先到达 API Server 的更新会被存储其余调度器需将 Pod 重新入队等待声明恢复可用见reservedFor的字段说明。七、源码扩展阅读指引模型主文件kubernetes/aio/client/models/v1beta2_resource_claim.py同步版模型kubernetes/client/models/v1beta2_resource_claim.pyspec 与 statusv1beta2_resource_claim_spec.py、v1beta2_resource_claim_status.py设备请求相关v1beta2_device_claim.py、v1beta2_device_request.py、v1beta2_exact_device_request.py、v1beta2_device_sub_request.py分配状态相关v1beta2_allocation_result.py、v1beta2_allocated_device_status.py、v1beta2_resource_claim_consumer_reference.pyAPI 层kubernetes/aio/client/api/resource_v1beta2_api.py异步、kubernetes/client/api/resource_v1beta2_api.py同步OpenAPI 定义scripts/swagger.jsonv1beta2.ResourceClaim等定义客户端方法索引kubernetes/README.md结语V1beta2ResourceClaim是官方 Kubernetes Python 客户端中表达 DRA 资源请求的标准载体它以spec.devices描述要什么设备、满足什么约束以status承载分配结果与消费方预留配合ResourceV1beta2Api的 CRUD 方法即可完整落地按需分配加速器/网卡等异构设备的典型场景。理解其驼峰别名、不可变 spec 与各 feature gate 前提是正确、安全地使用这一 alpha 类型的基础。赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐Kubernetes Python 客户端 V1ResourceClaimTemplateSpec 模型详解Dynamic Resource Allocation 的资源声明模板开发指南Kubernetes Python 客户端 V1ResourceClaimTemplateSpec 模型详解Dynamic Resource Allocati后端云原生容器编排Kubernetes Python 客户端 V1ResourceSliceSpec 模型详解Dynamic Resource Allocation 资源切片声明与序列化实践Kubernetes Python 客户端 V1ResourceSliceSpec 模型详解Dynamic Resource Allocation 资源切片声后端云原生容器编排Kubernetes Python 客户端 V1beta2ResourceSliceSpec 模型全解析Dynamic Resource Allocation 的资源发布协议Kubernetes Python 客户端 V1beta2ResourceSliceSpec 模型全解析Dynamic Resource Allocation后端云原生容器编排创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考