Kubernetes Python 客户端 V1beta1DeviceAllocationResult 模型详解：DRA v1beta1 设备分配结果字段与序列化指南

后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载本文围绕 Kubernetes 官方 Python 客户端本仓库含同步kubernetes.client与异步kubernetes.aio.client两套实现中的V1beta1DeviceAllocationResult模型展开它是 Dynamic Resource AllocationDRA动态资源分配v1beta1 APIresource.k8s.io/v1beta1中描述设备分配结果的核心数据结构。读完本文你将掌握该模型的全部字段语义、pydantic 校验与序列化行为、它在ResourceClaimStatus→AllocationResult→DeviceAllocationResult对象链中的位置以及如何在代码中构造、解析和序列化这一模型。一、背景DRA 与 DeviceAllocationResult 的定位Kubernetes 的 Dynamic Resource AllocationDRA允许用户通过ResourceClaim资源声明和DeviceClass设备类以声明式方式申请 GPU、FPGA 等异构设备由 DRA driver 负责实际的设备分配。分配完成后分配结果会写入ResourceClaim的status.allocation字段其类型为V1beta1AllocationResult而该对象中的devices字段正是V1beta1DeviceAllocationResult。从源码结构可以梳理出如下对象嵌套链V1beta1ResourceClaimStatus └── allocation: V1beta1AllocationResult ├── allocationTimestamp: datetime ├── devices: V1beta1DeviceAllocationResult ← 本文主题 │ ├── config: List[V1beta1DeviceAllocationConfiguration] │ └── results: List[V1beta1DeviceRequestAllocationResult] └── nodeSelector: V1NodeSelector这条链在 v1beta1_resource_claim_status.py 与 v1beta1_allocation_result.py 中有明确体现V1beta1ResourceClaimStatus.allocation指向V1beta1AllocationResult而V1beta1AllocationResult.devices的类型正是V1beta1DeviceAllocationResult。本模型的 API 参考文档位于 doc/source/kubernetes.aio.client.models.v1beta1_device_allocation_result.rst通过 Sphinxautomodule指令从模块 v1beta1_device_allocation_result.py 自动生成其 OpenAPI 定义源则位于仓库的 scripts/swagger.json。二、模型定义类签名与 pydantic 行为V1beta1DeviceAllocationResult定义在kubernetes.aio.client.models.v1beta1_device_allocation_result模块中是一个继承自pydantic.BaseModel的模型类与同步客户端kubernetes/client/models/v1beta1_device_allocation_result.py中的实现对应。其官方语义为DeviceAllocationResult is the result of allocating devices.类的核心定义如下摘自 v1beta1_device_allocation_result.pyclass V1beta1DeviceAllocationResult(BaseModel): config: Optional[List[V1beta1DeviceAllocationConfiguration]] Field(defaultNone, ...) results: Optional[List[V1beta1DeviceRequestAllocationResult]] Field(defaultNone, ...) model_config ConfigDict( validate_by_nameTrue, validate_by_aliasTrue, validate_assignmentTrue, extraforbid, protected_namespaces(), )其model_config的每一项都值得关注配置项取值含义validate_by_nameTrue允许按 Python 属性名config、results校验输入validate_by_aliasTrue同时允许按 API 别名wire name校验输入validate_assignmentTrue在赋值时执行 pydantic 校验非法类型会在运行期被拦截extraforbid拒绝未知字段传入未声明的键会直接报错保证与 API 契约严格一致protected_namespaces()解除 pydantic 对model_*等保留前缀的默认限制同步与异步两套实现的行为保持一致异步版本通过from __future__ import annotations延后类型求值便于在kubernetes.aio.client异步包内复用同一套模型定义。三、核心字段详解V1beta1DeviceAllocationResult仅有config与results两个字段二者均为可选defaultNone的列表。在 OpenAPI 定义中两者都标注了x-kubernetes-list-type: atomic见 scripts/swagger.json即整个列表被视为一个原子单元整体替换。3.1 config分配配置参数类型Optional[List[V1beta1DeviceAllocationConfiguration]]。字段语义来自模型 docstring该字段是所有 claim资源声明与 class设备类配置参数的组合。DRA driver 可以根据配置中的标志flag区分配置究竟来自 claim 还是 class。值得强调的是该列表也包含那些在结果中没有分配到设备的 driver 的配置参数因为最终支持哪些配置参数由各 driver 自行决定driver 可以静默忽略silently ignore它们不认识的配置参数因此该字段对未知配置具备天然的向后兼容性。每个config元素是V1beta1DeviceAllocationConfiguration见 v1beta1_device_allocation_configuration.py包含三个字段字段类型说明opaqueOptional[V1beta1OpaqueDeviceConfiguration]由 driver 厂商自定义格式的配置参数见下文requestsOptional[List[str]]该配置适用的请求名列表为空时表示适用于所有请求。引用子请求subrequest时需采用main request[/subrequest]格式若只写主请求名则配置应用于其所有子请求sourcestr必填记录配置来源来自 class设备类还是来自 claim。从源码描述可以推断该字段用于区分普通用户无法设置的类级配置与用户可设置的声明级配置其中opaque对应的V1beta1OpaqueDeviceConfiguration见 v1beta1_opaque_device_configuration.py是 DRA 向 driver 传递任意配置的通用容器字段类型说明driverstr必填用于确定由哪个 kubelet 插件接收这些配置参数必须是 DNS 子域且应以 driver 厂商拥有的 DNS 域结尾仅使用小写字符parametersDict[str, Any]必填任意数据校验与版本化由 driver 开发者负责通常包含自标识与版本信息如 Kubernetes 类型的kindapiVersion原始数据长度必须小于或等于 10 Ki3.2 results已分配设备列表类型Optional[List[V1beta1DeviceRequestAllocationResult]]。字段语义列出所有已分配的设备。每个元素对应一次请求的分配结果其类型为V1beta1DeviceRequestAllocationResult见 v1beta1_device_request_allocation_result.py共含 11 个字段字段类型必填说明devicestr是通过 driver 资源池中的名称引用一个设备实例必须是 DNS 标签driverstr是DRA driver 名称其 kubelet 插件在 claim 需要被用到节点上时负责处理分配必须是 DNS 子域、以小写字符组成poolstr是与driver、device共同唯一标识被分配的设备完整格式为driver name/pool name/device name长度不超过 253 字符可包含由斜杠分隔的多个 DNS 子域requeststr是引起该设备被分配的 claim 内请求名若引用的是DeviceRequest的firstAvailable列表中的子请求则必须采用main request/subrequest格式同一请求可能分配多个设备adminAccessOptional[bool]否表示该设备是否为管理访问administrative access而分配未设置或为false时管理访问关闭否则开启。alpha 字段需启用DRAAdminAccessfeature gatebindingConditionsOptional[List[str]]否分配时对应ResourceSlice上BindingConditions的副本。beta 字段需启用DRADeviceBindingConditions与DRAResourceClaimDeviceStatusfeature gatesbindingFailureConditionsOptional[List[str]]否分配时对应ResourceSlice上BindingFailureConditions的副本feature gate 要求同上consumedCapacityOptional[Dict[str, str]]否记录该设备在 claim 请求中按设备消耗的容量键为容量类型、值为resource.Quantity字符串消耗量可能因requestPolicy向上取整而大于请求量且每个设备总消耗不得超过DeviceCapacity的Value。仅对允许多次分配的设备填充零消耗条目也会被包含shareIDOptional[str]否当设备支持多个并发分配share时唯一标识单个分配份额作为同一设备并发份额的额外映射键skipNodeOperationsOptional[List[str]]否决定在节点上是否可跳过该设备的节点本地资源操作gRPC 调用列表若某 driver 在 claim 中所有已分配设备都跳过某操作则该 gRPC 调用会被整体跳过。是分配时刻ResourceSlice.spec.skipNodeOperations的副本OpenAPI 中标注为x-kubernetes-list-type: settolerationsOptional[List[V1beta1DeviceToleration]]否分配时刻请求中全部 tolerations 的副本最大数量为 16。beta 字段需启用DRADeviceTaintsfeature gate其中V1beta1DeviceToleration见 v1beta1_device_toleration.py与 Pod 的 toleration 语义一致通过key, value, effect三元组加匹配操作符operator描述 ResourceClaim 对设备污点的容忍effect允许值为NoSchedule与NoExecute为空匹配所有效果key为空时operator必须是Exists匹配所有键与值operator合法值为Exists和Equal默认为EqualtolerationSeconds仅对NoExecute生效零与负值会被系统按 0 处理立即驱逐。四、字段名映射snake_case 与 camelCase 的自动转换由于 Kubernetes API 使用 camelCase如shareID、skipNodeOperations而 Python 惯例使用 snake_case该模型族通过 pydantic 的AliasChoices同时接受两种命名share_id: Optional[StrictStr] Field( defaultNone, validation_aliasAliasChoices(shareID, share_id), serialization_aliasshareID, ... )对V1beta1DeviceAllocationResult本身config与results的别名与属性名相同无需转换。但其嵌套模型如V1beta1DeviceRequestAllocationResult在from_dict前会先经过__preprocess_input_names归一化见 v1beta1_device_request_allocation_result.py若输入字典只有 snake_case 键如share_id而没有 camelCase 键shareID会自动补齐后者并移除前者从而兼容两类输入来源。五、序列化与反序列化 API与仓库中其他 OpenAPI 生成模型一致V1beta1DeviceAllocationResult提供以下核心方法见 v1beta1_device_allocation_result.py方法作用to_str()返回pprint.pformat(self.to_dict())的格式化字符串便于调试打印__repr__复用该方法to_json()返回使用别名wire name的 JSON 字符串底层通过json.dumps(to_jsonable_python(...))处理from_json(json_str)从 JSON 字符串构造实例等价于from_dict(json.loads(json_str))to_dict(serializeFalse)返回所有声明字段的字典serializeTrue时输出 wire namecamelCase否则输出 Python 属性名snake_casefrom_dict(obj)从字典构造实例列表元素会递归调用V1beta1DeviceAllocationConfiguration.from_dict与V1beta1DeviceRequestAllocationResult.from_dict__eq__/__ne__基于to_dict()结果比较两个模型实例是否相等序列化内部通过_to_legacy_value/_to_openapi_value等辅助函数递归处理列表与字典元素确保嵌套模型config列表、results列表中的每个元素也能正确转换为纯 Python 对象或 OpenAPI 风格字典__openapi_generator_modern_projection会在model_dump(by_aliasTrue, exclude_noneTrue)的基础上仅保留初始化时显式设置的None字段从而避免序列化结果中混入大量无意义的空键。六、实战构造、解析与打印以下示例来自仓库同步生成的 V1beta1DeviceAllocationResult.md展示了模型的标准用法from kubernetes.aio.client.models.v1beta1_device_allocation_result import V1beta1DeviceAllocationResult # 方式一从 JSON 字符串构造json 为符合 API 契约的字符串 json {config: [], results: []} instance V1beta1DeviceAllocationResult.from_json(json) # 打印 JSON 字符串表示 print(V1beta1DeviceAllocationResult.to_json()) # 方式二转换为 dict 后再从 dict 构造形成往返转换 d instance.to_dict() instance2 V1beta1DeviceAllocationResult.from_dict(d)直接以 Python 对象方式构造同样可行字段均继承 pydantic 的赋值校验from kubernetes.aio.client.models.v1beta1_device_allocation_result import V1beta1DeviceAllocationResult from kubernetes.aio.client.models.v1beta1_device_request_allocation_result import V1beta1DeviceRequestAllocationResult result V1beta1DeviceRequestAllocationResult( driverexample.com/my-gpu-driver, poolpool-0, devicegpu-0001, requestgpu-request, ) allocation V1beta1DeviceAllocationResult(results[result]) print(allocation.to_dict()) # {config: None, results: [{adminAccess: None, ...}]}在真实场景中该模型通常不会单独出现而是随ResourceClaim的status.allocation.devices一并返回。使用异步客户端时可通过 resource_v1beta1_api.py 中的ResourceV1beta1Api调用read_namespaced_resource_claim等方法获取完整的V1beta1ResourceClaim对象再沿claim.status.allocation.devices路径读取设备分配明细。七、小结与参考V1beta1DeviceAllocationResult是理解 DRA v1beta1 分配结果的入口模型results回答分配了哪些设备、由谁分配、对应哪个请求config回答这些设备应使用哪些驱动级配置。掌握其字段语义特别是adminAccess、consumedCapacity、tolerations等与 feature gate 绑定的可选字段与序列化行为即可在 Kubernetes Python 客户端中准确读取和构造设备分配数据。相关源码与文档参考API 参考页doc/source/kubernetes.aio.client.models.v1beta1_device_allocation_result.rst模型实现异步kubernetes/aio/client/models/v1beta1_device_allocation_result.py模型实现同步kubernetes/client/models/v1beta1_device_allocation_result.py嵌套模型v1beta1_device_request_allocation_result.py、v1beta1_device_allocation_configuration.py、v1beta1_allocation_result.py上层对象v1beta1_resource_claim_status.py生成的 Markdown 文档kubernetes/aio/docs/V1beta1DeviceAllocationResult.mdOpenAPI 定义源scripts/swagger.json赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐Kubernetes Python 客户端 V1EndpointAddress 模型详解Endpoints 端点地址的结构、字段与序列化Kubernetes Python 客户端 V1EndpointAddress 模型详解Endpoints 端点地址的结构、字段与序列化 本篇技术指南围绕 K后端云原生容器编排Kubernetes Python 客户端 async 版 V1PriorityLevelConfigurationList 模型详解字段结构、序列化与 List 分页实践Kubernetes Python 客户端 async 版 V1PriorityLevelConfigurationList 模型详解字段结构、序列化与 Li后端云原生容器编排Kubernetes Python 客户端 V1AllocationResult 模型详解读懂动态资源分配DRA的分配结果结构Kubernetes Python 客户端 V1AllocationResult 模型详解读懂动态资源分配DRA的分配结果结构 V1AllocationR后端云原生容器编排创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考