Kubernetes Python 客户端 V1beta2CapacityRequestPolicyRange 模型详解：DRA 容量请求范围的 Min/Max/Step 语义与实战

后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载导读V1beta2CapacityRequestPolicyRange是 Kubernetes Python 客户端本项目即 官方 Python 客户端库中resource.k8s.io/v1beta2API 组下的一个数据模型用于描述 Dynamic Resource AllocationDRA动态资源分配中可消耗容量consumable capacity的合法取值范围即min/max/step三要素构成的容量配额区间。本文以 doc/source/kubernetes.aio.client.models.v1beta2_capacity_request_policy_range.rst 对应的模块为骨架结合仓库源码与同步 API 文档完整讲解该模型的字段含义、容量向上取整规则、整数/小数算术两种计算模式、JSON/dict 序列化接口以及它在V1beta2CapacityRequestPolicy→DeviceCapacity.requestPolicy组合中的实际用法帮助读者用 Python 客户端正确构造并解析 DRA 容量策略。一、模型定位DRA 容量请求策略中的范围组件V1beta2CapacityRequestPolicyRange定义于 kubernetes/aio/client/models/v1beta2_capacity_request_policy_range.py同步的非异步版本位于 kubernetes/client/models/v1beta2_capacity_request_policy_range.py两类客户端代码结构一致。从源码注释可知该客户端由 OpenAPI Generator 依据 Kubernetesrelease-1.37的 OpenAPI 文档自动生成类本身继承pydantic.BaseModel。在 DRA 体系里capacity是设备可提供的可消耗资源如显存、带宽额度而请求策略requestPolicy决定一次容量消费请求应该如何被校验与向上取整。策略包含三选一的取值方式validRange本模型、validValues离散值集合与default未显式请求时的默认消费量三者最多只能设置一种该约束见V1beta2CapacityRequestPolicy的类注释Must not set more than one ValidRequestValues实现于 kubernetes/aio/client/models/v1beta2_capacity_request_policy.py。从源码结构看本模型在整个 DRA 模型树中处于中间层V1beta2DeviceCapacity.requestPolicy持有V1beta2CapacityRequestPolicy见 kubernetes/client/models/v1beta2_device_capacity.pyV1beta2CapacityRequestPolicy.valid_range的类型正是本模型V1beta2CapacityRequestPolicyRange见 kubernetes/aio/client/models/v1beta2_capacity_request_policy.py消费请求则通过V1beta2CapacityRequirements.requestsDict[str, str]的 quantity 映射表达见 kubernetes/client/models/v1beta2_capacity_requirements.py。二、字段定义min / max / step 三要素模型包含三个字符串字段均表示 Kubernetesresource.Quantity形式的数量例如4Gi、500m字段类型是否可选含义与约束minstrStrictStr必填允许的最小消费容量。必须大于等于零且小于等于设备 capacity 值requestPolicy.default必须大于等于minmaxstrStrictStr可选允许请求的容量上限。必须小于等于设备 capacity 值min与requestPolicy.default必须小于等于maxstepstrStrictStr可选范围内合法容量值的步长。max若设置与requestPolicy.default必须是step的整数倍min step必须小于等于设备 capacity 值源码中的openapi_types与attribute_map一致地给出了三个字段见 kubernetes/aio/client/models/v1beta2_capacity_request_policy_range.pyopenapi_types: ClassVar[Dict[str, str]] { max: str, min: str, step: str } attribute_map: ClassVar[Dict[str, str]] { max: max, min: min, step: step }值得注意字段被声明为StrictStr且min无默认值必填max、step默认为None可选。在 JSON wire 格式中三个字段的 key 与属性名完全一致min/max/step没有驼峰别名差异。三、核心语义容量校验与向上取整规则根据模型类 docstringkubernetes/aio/client/models/v1beta2_capacity_request_policy_range.pyV1beta2CapacityRequestPolicyRange定义了可消耗容量的合法范围其调度校验逻辑按顺序执行低于下限 → 提升到下限如果请求量小于min向上取整为min设置 step → 对齐步长如果设置了step且请求量位于min与max之间但不对齐step则向上取整到下一个满足min (n * step)的值未设置 step → 原样放行如果未设置step只要请求量落在min到max若设置了max之间就按原值使用超过上限 → 拒绝分配如果请求量或取整后的值超过max若设置则该请求不满足策略设备不能被分配。这四条规则是 DRA 调度器对请求量进行最近合法值向上取整的完整闭环实际使用时只需保证模型字段填写正确校验逻辑由 Kubernetes 服务端scheduler 与 API server执行Python 客户端负责序列化与反序列化。3.1 整数与小数两种算术模式DRAFractionalCapacityRangedocstring 同时说明了一个重要的算术细节如果DRAFractionalCapacityRange特性门控feature gate已启用且min、max、step中至少一个是小数数量例如100m 0.1则改用 milli-unit千分之一单位算术支持最多 3 位小数此时可表示的最大值比使用 64 位整数时缩小 1000 倍。否则所有比较均通过resource.Quantity.Value()以 64 位整数算术完成。这一语义对构造策略参数有直接指导意义整数值场景如min1Gi、step256Mi走 64 位整数路径范围上限大需要小数容量如min100m、step250m时必须依赖DRAFractionalCapacityRange特性门控且能表示的数值上限相应降低——这是容量单位选择的重要约束不满足时应改用更大的单位如1而不是1000m来扩大表达范围。四、在 Python 客户端中的使用方式4.1 导入路径异步asyncio客户端与同步客户端分别提供导出两者均可直接使用# 异步客户端本关联文档对应的模块 from kubernetes.aio.client.models.v1beta2_capacity_request_policy_range import V1beta2CapacityRequestPolicyRange # 同步客户端等价实现 from kubernetes.client.models.v1beta2_capacity_request_policy_range import V1beta2CapacityRequestPolicyRange此外类还被收纳进models包与顶层包的__all__中异步侧见 kubernetes/aio/client/models/init.py 与 kubernetes/aio/client/init.py同步侧见 kubernetes/client/init.py因此也可以从聚合命名空间引用。4.2 实例化与序列化模型基于 pydantic v2构造函数直接接收三个字段仓库 API 文档 kubernetes/aio/docs/V1beta2CapacityRequestPolicyRange.md 给出了完整的 JSON/dict 互转示例整理为可直接运行的版本如下from kubernetes.aio.client.models.v1beta2_capacity_request_policy_range import V1beta2CapacityRequestPolicyRange # 1. 直接构造min 必填max / step 可选 policy_range V1beta2CapacityRequestPolicyRange( min1Gi, max4Gi, step256Mi, ) # 2. 从 JSON 字符串创建实例from_json 内部调用 from_dict json_str {min: 1Gi, max: 4Gi, step: 256Mi} instance V1beta2CapacityRequestPolicyRange.from_json(json_str) # 3. 输出 JSON 字符串表示按 alias即 min/max/step print(instance.to_json()) # 4. 转换为 dict字典 key 与字段同名 policy_range_dict instance.to_dict() print(policy_range_dict) # 5. 从 dict 还原实例 restored V1beta2CapacityRequestPolicyRange.from_dict(policy_range_dict) assert restored instance注意官方生成的示例文档中有一处笔误print(V1beta2CapacityRequestPolicyRange.to_json())以类名直接调用正确写法应是对实例调用instance.to_json()__eq__基于to_dict()结果比较因此往返转换后可直接用断言。4.3 序列化底层原理从源码看模型提供了两条序列化路径to_dict(serializeFalse)返回public or wire names的字段字典直接调用getattr读取min/max/stepkubernetes/aio/client/models/v1beta2_capacity_request_policy_range.py__openapi_generator_modern_projection基于 pydantic 的model_dump(by_aliasTrue, exclude_noneTrue)生成现代投影字典并借助_OPENAPI_GENERATOR_TO_DICT标记与to_dict双向关联kubernetes/aio/client/models/v1beta2_capacity_request_policy_range.pyto_json()优先走该路径以保证别名正确反序列化侧from_dict先校验输入必须是 dict然后调用model_validate逐个字段填充kubernetes/aio/client/models/v1beta2_capacity_request_policy_range.py。此外模型配置了extraforbidkubernetes/aio/client/models/v1beta2_capacity_request_policy_range.py这意味着传入min/max/step之外的未知字段会触发校验失败这有助于在 DRA 配置中提前发现字段拼写错误。五、组合实战将范围挂到容量请求策略上V1beta2CapacityRequestPolicyRange通常不作为独立对象直接提交而是作为V1beta2CapacityRequestPolicy.validRange的组成部分使用。构造一个完整的策略对象from kubernetes.aio.client.models.v1beta2_capacity_request_policy import V1beta2CapacityRequestPolicy from kubernetes.aio.client.models.v1beta2_capacity_request_policy_range import V1beta2CapacityRequestPolicyRange request_policy V1beta2CapacityRequestPolicy( valid_rangeV1beta2CapacityRequestPolicyRange( min1Gi, max4Gi, step256Mi, ), default2Gi, # 未显式请求时的默认消费量须满足 min default max 且是 step 的倍数 )源码揭示了这里的关键实现细节kubernetes/aio/client/models/v1beta2_capacity_request_policy.pyvalid_range: Optional[V1beta2CapacityRequestPolicyRange] Field( defaultNone, validation_aliasAliasChoices(validRange, valid_range), serialization_aliasvalidRange, )即传入时接受驼峰写法validRange也接受下划线写法valid_rangefrom_dict中的__preprocess_input_names会做归一化见 kubernetes/aio/client/models/v1beta2_capacity_request_policy.py序列化到 JSON 时统一输出为validRangeto_dict()默认输出键为下划线风格的valid_range而to_json()/现代投影会输出 wire 格式validRange且会递归调用子模型to_dict()kubernetes/aio/client/models/v1beta2_capacity_request_policy.py。5.1 结合 DeviceCapacity 与 CapacityRequirements 的完整流程按 kubernetes/client/models/v1beta2_capacity_requirements.py 的说明完整的使用链路为设备方在V1beta2DeviceCapacity.requestPolicy中声明容量策略内含validRange消费方在V1beta2CapacityRequirements.requests中按Dict[str, str]声明各容量域的请求数量当存在requestPolicy时请求量会依据策略向上取整到最近合法值若无法取整超出策略允许范围设备视为不可分配最终被消费的容量可能已被策略调整记录在资源声明的status.devices[*].consumedCapacity字段中。这一流程说明本模型虽小却是决定请求是否合法、设备能否被分配的关键判定依据之一。六、版本与适用范围本文所有字段定义与语义均取自当前仓库源码对应 OpenAPI 文档版本为release-1.37见模块头注释 kubernetes/aio/client/models/v1beta2_capacity_request_policy_range.py该模型属于resource.k8s.io/v1beta2API 组仓库同时提供v1、v1beta1的对应模型V1CapacityRequestPolicyRange、V1beta1CapacityRequestPolicyRange均已在 kubernetes/client/models/init.py 与 kubernetes/aio/client/models/init.py 中导出选型时应与目标集群实际启用的 API 版本对齐小数容量模式依赖DRAFractionalCapacityRange特性门控使用前需确认集群是否启用该门控并注意小数模式下数值上限缩小 1000 倍这一限制本文只描述模型在 Python 客户端中的查看、构造与序列化方式实际容量校验与向上取整由 Kubernetes 服务端执行客户端并不重复实现调度逻辑。七、进一步阅读模型源码异步kubernetes/aio/client/models/v1beta2_capacity_request_policy_range.py模型源码同步kubernetes/client/models/v1beta2_capacity_request_policy_range.py生成式 API 文档kubernetes/aio/docs/V1beta2CapacityRequestPolicyRange.md、kubernetes/docs/V1beta2CapacityRequestPolicyRange.md上层策略模型kubernetes/aio/client/models/v1beta2_capacity_request_policy.py关联容量模型kubernetes/client/models/v1beta2_capacity_requirements.py、kubernetes/client/models/v1beta2_device_capacity.py模型注册与导出kubernetes/aio/client/models/__init__.py、kubernetes/aio/client/__init__.py、kubernetes/client/__init__.py赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐Kubernetes Python 客户端 V1beta2CapacityRequestPolicy 模型详解DRA 设备容量消费策略的字段、语义与实战用法Kubernetes Python 客户端 V1beta2CapacityRequestPolicy 模型详解DRA 设备容量消费策略的字段、语义与实战用法后端云原生容器编排Kubernetes Python 客户端详解StorageV1TokenRequest 模型与 ServiceAccount Token 请求实战Kubernetes Python 客户端详解StorageV1TokenRequest 模型与 ServiceAccount Token 请求实战 本篇技术后端云原生容器编排Kubernetes Python 客户端深入解析V1ContainerExtendedResourceRequest 模型与 DRA 设备请求映射Kubernetes Python 客户端深入解析V1ContainerExtendedResourceRequest 模型与 DRA 设备请求映射 导读 本后端云原生容器编排上一篇Presto Accumulo Connector 完全指南从配置、索引查询到序列化与元数据管理下一篇EMQX 6.1.2 版本技术解读安全加固、路由 Schema v3 与集群稳定性改进全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考