后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载导读本文基于 Kubernetes 官方 Python 客户端仓库中doc/source/kubernetes.aio.client.models.v1_rolling_update_stateful_set_strategy.rst所对应的模型文档深入讲解异步客户端kubernetes.aio.client中V1RollingUpdateStatefulSetStrategy这一数据模型它承载 StatefulSet 滚动更新RollingUpdate策略的两个核心参数partition与maxUnavailable是配置金丝雀发布、分批发布的关键模型。读完本文你将掌握该模型的字段语义、Python 侧属性命名与 JSON 字段名的映射规则、在V1StatefulSetUpdateStrategy中的嵌套位置以及如何用同步客户端kubernetes.client与异步客户端kubernetes.aio.client在真实代码中配置和使用它。一、模型定位StatefulSet 更新策略的最小组成单元在 Kubernetes 中StatefulSet 的spec.updateStrategy控制控制器StatefulSet controller如何执行更新。Kubernetes 提供两种更新策略类型OnDelete不自动更新只有管理员手动删除 Pod 后控制器才基于新模板重建RollingUpdate默认按序滚动更新可配合partition实现金丝雀发布配合maxUnavailable控制更新期间的不可用 Pod 数量。V1RollingUpdateStatefulSetStrategy正是RollingUpdate类型下携带具体参数的模型。从源码可以看出其与上层模型的关系在 v1_stateful_set_update_strategy.py 中V1StatefulSetUpdateStrategy包含两个字段rolling_updateJSON 字段名rollingUpdate类型为Optional[V1RollingUpdateStatefulSetStrategy]typeJSON 字段名type类型为Optional[str]默认为RollingUpdate。即当V1StatefulSetUpdateStrategy.type RollingUpdate时通过rollingUpdate字段携带本模型的partition与maxUnavailable参数。V1StatefulSetUpdateStrategy再作为V1StatefulSetSpec.update_strategyJSON 字段名updateStrategy字段挂载到 StatefulSet 的 Spec 中从而构成“StatefulSet → Spec → updateStrategy → rollingUpdate → partition/maxUnavailable”的完整链路。二、字段语义partition 与 maxUnavailableV1RollingUpdateStatefulSetStrategy定义于 v1_rolling_update_stateful_set_strategy.py仅包含两个可选字段。以下说明以源码中的description即 OpenAPI release-1.37 定义为准。2.1 partition金丝雀发布的核心开关Python 属性名partitionJSON 字段名partition类型Optional[int]StrictInt默认值0语义partition表示 StatefulSet 从哪个序号ordinal开始分区更新。滚动更新时序号从Replicas-1到partition的 Pod 会被更新序号从partition-1到0的 Pod 保持不动。默认值为0即全部更新。这是实现金丝雀canary部署的关键机制例如一个replicas5的 StatefulSet设置partition4后只有序号 4 的 Pod 会被更新其余序号 03 的 Pod 维持旧版本验证新版本无误后再逐步调低partition如 3、2、1、0以扩大更新范围直至全量更新。2.2 maxUnavailable不可用 Pod 上限Python 属性名max_unavailableJSON 字段名maxUnavailable类型Optional[int | str]StrictInt | StrictStr即 IntOrString 类型默认值1语义更新期间最多允许不可用的 Pod 数量。取值可以是绝对数字如5也可以是期望 Pod 数的百分比如10%百分比按向上取整rounding up换算为绝对数字。该值不能为 0。源码中对该字段有两点重要补充说明该字段处于 beta 级别且默认启用作用于序号 0 到Replicas-1范围内的所有 Pod——只要该范围内存在不可用 Pod都会被计入maxUnavailable该设置在OrderedReady的podManagementPolicy下可能不生效——因为该策略保证 Pod 一个个被创建并变为就绪ready滚动更新的推进方式与maxUnavailable的预期可能不一致。从源码类型注解看max_unavailable被声明为Optional[StrictInt | StrictStr]属于 Kubernetes 中典型的 IntOrString 字段与V1RollingUpdateDaemonSet.max_unavailable、V1RollingUpdateDeployment.max_unavailable、V1PodDisruptionBudgetSpec.max_unavailable等字段的形态一致。三、模型实现机制属性映射、校验与序列化该模型由 OpenAPI Generator 根据apps/v1的 Swagger 定义见 scripts/swagger.json自动生成底层基于 PydanticBaseModel。理解其实现机制有助于在实际调用中避免踩坑。3.1 蛇形命名与驼峰命名的自动转换模型通过Field(validation_aliasAliasChoices(...), serialization_alias...)实现 Python 蛇形命名与 Kubernetes JSON 驼峰命名的双向映射max_unavailable: Optional[StrictInt | StrictStr] Field( defaultNone, validation_aliasAliasChoices(maxUnavailable, max_unavailable), serialization_aliasmaxUnavailable, ... ) partition: Optional[StrictInt] Field( defaultNone, description..., )alias_map与openapi_types类变量进一步明确了映射关系openapi_types: ClassVar[Dict[str, str]] { max_unavailable: object, partition: int } attribute_map: ClassVar[Dict[str, str]] { max_unavailable: maxUnavailable, partition: partition } __properties: ClassVar[List[str]] [maxUnavailable, partition]__preprocess_input_names类方法负责在from_dict时兼容两种命名当输入 dict 中只有max_unavailable而没有maxUnavailable时会自动转换为maxUnavailable从而保证直接传字典也能被正确解析。3.2 模型配置严格校验与序列化行为model_config使用以下配置model_config ConfigDict( validate_by_nameTrue, validate_by_aliasTrue, validate_assignmentTrue, extraforbid, protected_namespaces(), )validate_by_nameTruevalidate_by_aliasTrue构造时既可按 Python 属性名max_unavailable传参也可按 JSON 别名maxUnavailable传参validate_assignmentTrue赋值时同样触发类型校验防止运行时把错误类型写入字段extraforbid禁止传入未声明的多余字段传入未知键会报错——这是自动生成客户端保证与 OpenAPI 契约一致性的重要手段。3.3 序列化与反序列化入口模型提供完整的 JSON 互转能力to_dict(serializeFalse)返回 Python 侧命名max_unavailable、partition的字典to_dict(serializeTrue)返回 wire 侧命名maxUnavailable、partition的字典to_json()返回使用别名的 JSON 字符串from_dict()从字典构造实例内部先调用__preprocess_input_names归一化命名再执行model_validatefrom_json()从 JSON 字符串构造实例。例如序列化输出形如strategy V1RollingUpdateStatefulSetStrategy(partition2, max_unavailable25%) strategy.to_dict(serializeTrue) # {maxUnavailable: 25%, partition: 2}3.4 IntOrString 双形态的测试验证仓库测试 test_generated_api.py 专门验证了这类 IntOrString 字段能同时接受整数与字符串两种表示。测试中V1RollingUpdateStatefulSetStrategy的max_unavailable字段被列入用例使用25%字符串与1整数分别构造模型并断言getattr(model, field)返回值与传入值一致model.model_dump(by_aliasTrue)[wire_name]即maxUnavailable与传入值一致。该测试同时覆盖了V1RollingUpdateDaemonSet、V1RollingUpdateDeployment、V1PodDisruptionBudgetSpec等模型证明“百分比字符串 / 绝对数字”双形态是整个客户端库对 IntOrString 字段的统一处理约定。四、在代码中使用同步客户端实战以下基于仓库示例 rollout-statefulset.py 展开。示例演示了创建无头 Service、创建 StatefulSet、更新镜像、列出 ControllerRevision 以及回滚到指定 revision 的完整流程其中更新 StatefulSet 的环节正是updateStrategy发挥作用的地方。4.1 创建带滚动更新策略的 StatefulSetfrom kubernetes import client, config config.load_kube_config() apps_v1_api client.AppsV1Api() # 构建容器与 Pod 模板 container client.V1Container( namests-redis, imageredis, image_pull_policyIfNotPresent, ports[client.V1ContainerPort(container_port6379)], ) template client.V1PodTemplateSpec( metadataclient.V1ObjectMeta(labels{app: redis}), specclient.V1PodSpec(containers[container]), ) # 显式声明 RollingUpdate 策略 # partition2 表示只更新序号 2 的 Pod实现金丝雀发布 strategy client.V1RollingUpdateStatefulSetStrategy( partition2, max_unavailable1, # 或 25% ) update_strategy client.V1StatefulSetUpdateStrategy( typeRollingUpdate, rolling_updatestrategy, ) spec client.V1StatefulSetSpec( replicas5, service_nameredis-test-svc, selectorclient.V1LabelSelector(match_labels{app: redis}), templatetemplate, update_strategyupdate_strategy, ) statefulset client.V1StatefulSet( api_versionapps/v1, kindStatefulSet, metadataclient.V1ObjectMeta(namestatefulset-redis), specspec, ) apps_v1_api.create_namespaced_stateful_set( namespacedefault, bodystatefulset )max_unavailable传整数1或字符串25%均可见上文 3.4 节的测试依据。4.2 更新镜像并调整 partition 推进发布创建完成后可通过patch_namespaced_stateful_set更新镜像并按需调整update_strategy。仓库示例的做法是先改镜像再整体 patchdef update_stateful_set(apps_v1_api, statefulset): # 更新容器镜像 statefulset.spec.template.spec.containers[0].image redis:6.2 statefulset_name statefulset.metadata.name apps_v1_api.patch_namespaced_stateful_set( namestatefulset_name, namespacedefault, bodystatefulset )金丝雀验证通过后可进一步把partition从2调低到0使全部 Pod 完成更新statefulset.spec.update_strategy.rolling_update.partition 0 apps_v1_api.patch_namespaced_stateful_set( namestatefulset.metadata.name, namespacedefault, bodystatefulset )4.3 回滚到指定 ControllerRevisionStatefulSet 每次变更模板都会生成新的 ControllerRevision。仓库示例通过读取指定 revision 的data字段并整体 patch 回去实现回滚def rollout_namespaced_stateful_set(apps_v1_api, name, namespace, controller_revision_name): _controller_revision apps_v1_api.read_namespaced_controller_revision( controller_revision_name, namespace) apps_v1_api.patch_namespaced_stateful_set( name, namespace, body_controller_revision.data)需要注意示例文件头部注明若 Kubernetes 版本低于 1.22不含 1.22kubernetes-client 版本也需低于 1.22——因为StatefulSetStatus.availableReplicas字段自 1.22 起原生支持客户端与服务端版本不匹配可能抛出ValueError。五、异步客户端kubernetes.aio.client的使用方式本文档所在路径doc/source/kubernetes.aio.client.models.v1_rolling_update_stateful_set_strategy.rst归属于异步客户端kubernetes.aio.client该客户端基于asyncio通过httpx执行非阻塞 HTTP 调用。模型类与同步客户端共享同一份 Swagger 契约OpenAPI release-1.37字段、类型与语义完全一致。在 kubernetes/aio/client/models/init.py 与 kubernetes/aio/client/init.py 中V1RollingUpdateStatefulSetStrategy均已导出因此可以直接导入使用from kubernetes.aio.client import V1RollingUpdateStatefulSetStrategy strategy V1RollingUpdateStatefulSetStrategy( partition1, max_unavailable10%, ) print(strategy.partition) # 1 print(strategy.max_unavailable) # 10% print(strategy.to_dict()) # {max_unavailable: 10%, partition: 1} print(strategy.to_dict(serializeTrue)) # {maxUnavailable: 10%, partition: 1}异步完整用法可参考仓库的 examples_asyncio 目录如 patch.py整体模式为load_kube_config后创建AppsV1Api等客户端再以async with/await方式调用create_namespaced_stateful_set、patch_namespaced_stateful_set等异步方法。一个典型的异步创建/更新片段import asyncio from kubernetes import config from kubernetes.aio import client as aio_client async def main(): await config.load_kube_config() async with aio_client.ApiClient() as api: apps_v1_api aio_client.AppsV1Api(api) strategy aio_client.V1RollingUpdateStatefulSetStrategy( partition2, max_unavailable25%) update_strategy aio_client.V1StatefulSetUpdateStrategy( typeRollingUpdate, rolling_updatestrategy) # ... 构造 spec 与 statefulset ... await apps_v1_api.create_namespaced_stateful_set( namespacedefault, bodystatefulset) asyncio.run(main())六、常见问题与注意事项partition默认值为 0不设置rolling_update或partition时滚动更新默认全量更新所有 Pod 从Replicas-1到 0 依次更新。要实现金丝雀发布必须显式设置partition大于 0。max_unavailable不能为 0传入0会被 API 服务端拒绝需要“零不可用”时请考虑与maxSurge配合的 Deployment 策略StatefulSet 滚动更新本身不支持maxSurge。OrderedReady下max_unavailable可能不生效podManagementPolicy为OrderedReady默认值时Pod 逐个就绪后才创建下一个这与max_unavailable的语义存在冲突源码注释明确提示该设置此时可能不产生预期效果。extraforbid的严格校验构造模型时传入未声明字段如手滑写成maxUnavaliable会触发校验错误而不是静默忽略。版本匹配问题参考 rollout-statefulset.py 的说明客户端与集群版本差异过大可能因字段版本差异如availableReplicas抛ValueError生产环境应保持版本对齐。七、扩展阅读模型源码v1_rolling_update_stateful_set_strategy.py上层模型 v1_stateful_set_update_strategy.py模型注册与导出kubernetes/aio/client/init.py 与 kubernetes/aio/client/models/init.pyIntOrString 字段测试kubernetes/test/test_generated_api.py同步客户端完整示例examples/rollout-statefulset.py异步客户端示例examples_asyncioAPI 原始定义scripts/swagger.jsonapps/v1下io.k8s.api.apps.v1.RollingUpdateStatefulSetStrategy。赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐SEALSelf-Adapting Language Models如何革新AI自适应学习能力全面解析SEALSelf Adapting Language Models如何革新AI自适应学习能力全面解析 SEALSelf Adapting Language如何基于X-BUILD打造团队专属脚手架企业级定制化方案如何基于X BUILD打造团队专属脚手架企业级定制化方案 X BUILD是一个基于Vite2 Vue3 TypeScript构建的前端脚手架它提供了Kubernetes Python 客户端中的 V1StatefulSetOrdinals 模型StatefulSet 副本序号策略解析Kubernetes Python 客户端中的 V1StatefulSetOrdinals 模型StatefulSet 副本序号策略解析 本文围绕 kuber后端云原生容器编排上一篇FontStash跨平台部署指南Windows、Linux和macOS全平台适配下一篇CANN/GE ACL BLAS矩阵乘句柄创建API创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考