后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载V1StatefulSet是 kubernetes Python 客户端aio 异步版本中对应 Kubernetesapps/v1StatefulSet 资源的 Pydantic 数据模型。本文基于仓库中的 API 参考文档 kubernetes.aio.client.models.v1_stateful_set.rst 及其背后的生成代码 v1_stateful_set.py完整讲解该模型的字段构成、spec/status子模型、序列化与别名处理机制并给出在异步客户端kubernetes.aio中创建、更新和滚动回滚 StatefulSet 的可运行示例帮助你把官方文档骨架落地为实际可用的异步运维代码。1. 参考文档与模型的位置仓库中的 API 参考文档 kubernetes.aio.client.models.v1_stateful_set.rst 通过 Sphinx 的automodule指令直接引用kubernetes.aio.client.models.v1_stateful_set模块kubernetes.aio.client.models.v1\_stateful\_set module .. automodule:: kubernetes.aio.client.models.v1_stateful_set :members: :show-inheritance: :undoc-members:也就是说文档页呈现的内容完全由源码中的类定义、字段声明与 docstring 决定。同族的参考文档还包括kubernetes.aio.client.models.v1_stateful_set_spec.rstkubernetes.aio.client.models.v1_stateful_set_status.rstkubernetes.aio.client.models.v1_stateful_set_condition.rstkubernetes.aio.client.models.v1_stateful_set_list.rst对应的源码文件位于kubernetes/aio/client/models/目录下均由 OpenAPI Generator 根据 swagger.jsonOpenAPI 版本release-1.37见模块头部注释生成文件内明确标注 Do not edit the class manually即生产环境中不应手工修改这些模型文件。2. V1StatefulSet 顶层字段在 v1_stateful_set.py 中V1StatefulSet继承自 PydanticBaseModel其类 docstring 给出了资源语义StatefulSet represents a set of pods with consistent identities. Identities are defined as:Network: A single stable DNS and hostname.Storage: As many VolumeClaims as requested.The StatefulSet guarantees that a given network identity will always map to the same storage identity.即 StatefulSet 为 Pod 提供稳定的网络身份DNS/主机名和稳定的存储身份与 Pod 一一对应的 PVC。顶层共 5 个字段Python 字段线上 JSON 字段alias类型是否必填说明api_versionapiVersionOptional[StrictStr]否对象表示的版本化 schema如apps/v1kindkindOptional[StrictStr]否REST 资源类型如StatefulSetmetadatametadataOptional[V1ObjectMeta]否标准元数据name、namespace、labels 等specspecV1StatefulSetSpec是StatefulSet 规约唯一不可省略的字段statusstatusOptional[V1StatefulSetStatus]否由控制器维护的当前状态两个 ClassVar 属性辅助框架工作openapi_types: ClassVar[Dict[str, str]] { api_version: str, kind: str, metadata: V1ObjectMeta, spec: V1StatefulSetSpec, status: V1StatefulSetStatus } attribute_map: ClassVar[Dict[str, str]] { api_version: apiVersion, kind: kind, metadata: metadata, spec: spec, status: status }openapi_types记录字段到类型的映射attribute_map记录 Python 属性名到线上 JSON 键名的映射蛇形命名 ↔ 驼峰命名这是 OpenAPI Generator python 系模板的通用约定。2.1 模型配置别名验证与未知字段拒绝v1_stateful_set.py 中的model_config值得注意model_config ConfigDict( validate_by_nameTrue, validate_by_aliasTrue, validate_assignmentTrue, extraforbid, protected_namespaces(), )validate_by_nameTruevalidate_by_aliasTrue构造和反序列化时字段既可以用 Python 名api_version也可以用线上 aliasapiVersion传入二者等价extraforbid传入未声明的字段会直接触发 Pydantic 校验错误这能尽早发现字段拼写错误但也意味着客户端模型比集群旧、而返回了新增字段时或集群比客户端新会抛校验异常——examples/rollout-statefulset.py 头部的注释正是这个原因If your kubernetes version is lower than 1.22 (exclude 1.22), the kubernetes-client version must be lower than 1.22 ... Because new feature AvailableReplicas for StatefulSetStatus is supported in native kubernetes since version 1.22, mismatch version between kubernetes and kubernetes-client will raise exception ValueError.即模型与集群版本不匹配时V1StatefulSetStatus.available_replicas这类字段可能引起异常选型时需注意客户端版本与集群 API 版本的兼容。3. V1StatefulSetSpec规约字段逐项解析spec子模型定义在 v1_stateful_set_spec.py。字段及 docstring 语义如下Python 字段线上字段类型说明replicasreplicasOptional[int]期望副本数不指定时默认为 1selectorselectorV1LabelSelector必填。Pod 选择器决定该 StatefulSet 管理哪些 Podservice_nameserviceNameOptional[str]治理该 StatefulSet 的 Service 名称必须在 StatefulSet 之前创建负责网络身份Pod 的 DNS 形如pod-specific-string.serviceName.default.svc.cluster.localtemplatetemplateV1PodTemplateSpec必填。Pod 模板volume_claim_templatesvolumeClaimTemplatesOptional[List[V1PersistentVolumeClaim]]模板化 PVC 列表列表中每个 claim 必须在 template 的某个容器里有同名volumeMount同名 claim 优先于 template 中的 volumepod_management_policypodManagementPolicyOptional[str]OrderedReady默认按 pod-0、pod-1… 顺序创建并等待就绪缩容时反向删除Parallel并行创建、缩容时一次性删除全部update_strategyupdateStrategyOptional[V1StatefulSetUpdateStrategy]更新策略默认RollingUpdaterevision_history_limitrevisionHistoryLimitOptional[int]保留的 ControllerRevision 历史数量默认 10min_ready_secondsminReadySecondsOptional[int]新 Pod 创建后需连续 Ready 且无容器崩溃的最短秒数默认 0ordinalsordinalsOptional[V1StatefulSetOrdinals]副本序号起点见 3.1persistent_volume_claim_retention_policypersistentVolumeClaimRetentionPolicyOptional[V1StatefulSetPersistentVolumeClaimRetentionPolicy]PVC 保留策略见 3.23.1 ordinals副本序号起点v1_stateful_set_ordinals.py 中只有一个字段startstart is the number representing the first replicas index. It may be used to number replicas from an alternate index (eg: 1-indexed) over the default 0-indexed names, or to orchestrate progressive movement of replicas from one StatefulSet to another. If set, replica indices will be in the range[.spec.ordinals.start, .spec.ordinals.start .spec.replicas). If unset, defaults to 0.即默认 Pod 编号从0开始pod-0…pod-N-1设置ordinals.start后可从其他索引编号典型场景是把副本从一个 StatefulSet 渐进迁移到另一个。3.2 PVC 保留策略v1_stateful_set_persistent_volume_claim_retention_policy.py 提供两个正交维度when_deleted线上字段whenDeletedStatefulSet 被删除时对volumeClaimTemplates生成的 PVC 的处理。默认RetainPVC 不受影响设为Delete则一并删除when_scaled线上字段whenScaledStatefulSet缩容时的处理。默认Retain设为Delete则删除超出目标副本数的 Pod 对应的 PVC。3.3 updateStrategy更新策略与 maxUnavailablev1_stateful_set_update_strategy.py 中的type字段说明Type indicates the type of the StatefulSetUpdateStrategy. Default is RollingUpdate.RollingUpdate具体参数在 v1_rolling_update_stateful_set_strategy.py 中核心是max_unavailable线上字段maxUnavailableThe maximum number of pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). ... This can not be 0. Defaults to 1.支持绝对数或百分比两种写法不能为 0默认 1docstring 同时提示该设置对OrderedReady策略可能不完全生效因为 OrderedReady 本身就要求严格顺序。4. V1StatefulSetStatus状态字段与 Condition状态子模型定义在 v1_stateful_set_status.pyPython 字段线上字段类型说明replicasreplicasint必填。StatefulSet 控制器创建的 Pod 总数ready_replicasreadyReplicasOptional[int]处于 Ready 条件的 Pod 数current_replicascurrentReplicasOptional[int]由currentRevision版本创建的 Pod 数updated_replicasupdatedReplicasOptional[int]由updateRevision版本创建的 Pod 数available_replicasavailableReplicasOptional[int]可用 Pod 数Ready 至少 minReadySecondsKubernetes 1.22 引入current_revisioncurrentRevisionOptional[str]生成序列[0, currentReplicas)内 Pod 的 StatefulSet 版本update_revisionupdateRevisionOptional[str]生成序列[replicas-updatedReplicas, replicas)内 Pod 的版本observed_generationobservedGenerationOptional[int]控制器观测到的最新 generationAPI Server 在变更时更新collision_countcollisionCountOptional[int]控制器创建新 ControllerRevision 名称时的哈希碰撞计数conditionsconditionsOptional[List[V1StatefulSetCondition]]最新状态观测条件列表V1StatefulSetConditionv1_stateful_set_condition.py包含四个字段type条件类型如ReadystatusTrue/False/Unknownlast_transition_time线上lastTransitionTime条件最近一次状态跳变的时间datetime类型reason/message跳变原因与补充信息。在脚本中判断就绪与否通常就是轮询status.conditions里type Ready且status True的条目或比较ready_replicas与replicas。5. 序列化机制to_dict / to_json / from_dict这一部分是 aio 客户端模型相对老版同步客户端的关键变化所有模型改为 PydanticBaseModel并在模块级提供了一组兼容工具函数见 v1_stateful_set.py。5.1 from_dict / from_json反序列化v1_stateful_set.py 中classmethod def from_dict(cls, obj: Optional[Dict[str, Any]]) - Optional[Self]: Create an instance of V1StatefulSet from a dict if obj is None: return None if not isinstance(obj, dict): return cls.model_validate(obj) obj _cast(Dict[str, Any], cls.__preprocess_input_names(obj, remove_hidden_storage_namesTrue)) _obj cls.model_validate({ apiVersion: obj.get(apiVersion), kind: obj.get(kind), metadata: V1ObjectMeta.from_dict(obj[metadata]) if obj.get(metadata) is not None else None, spec: V1StatefulSetSpec.from_dict(obj[spec]) if obj.get(spec) is not None else None, status: V1StatefulSetStatus.from_dict(obj[status]) if obj.get(status) is not None else None }) return _obj三个要点递归构造metadata、spec、status分别交给对应子模型的from_dict形成整棵资源树的对象图spec的“必填”是软约束from_dict中obj.get(spec) is not None else None会把缺失的 spec 映射为None真正的必填性由 Pydantic 在model_validate时把关__preprocess_input_names把蛇形键名归一到驼峰键名例如输入里写api_version会自动搬到apiVersion保证两种写法都能通过校验。from_json(cls, json_str)则等价于cls.from_dict(json.loads(json_str))。5.2 to_dict / to_json序列化与别名def to_dict(self, serialize: bool False) - Dict[str, Any]: Return all declared model fields using public or wire names. return { (apiVersion if serialize else api_version): _to_legacy_value(getattr(self, api_version, None), serialize), (kind if serialize else kind): _to_legacy_value(getattr(self, kind, None), serialize), (metadata if serialize else metadata): _to_legacy_value(getattr(self, metadata, None), serialize), (spec if serialize else spec): _to_legacy_value(getattr(self, spec, None), serialize), (status if serialize else status): _to_legacy_value(getattr(self, status, None), serialize), }serializeFalse默认返回 Python 属性名api_version且嵌套值原样带出serializeTrue键名转换为线上 wire 名apiVersion并递归调用嵌套模型的to_dict(serializeTrue)经由_to_legacy_value这是发往 API Server 的 payload 形态。to_json则走另一条“现代投影”路径v1_stateful_set.pydef to_json(self) - str: to_openapi_to_dict _get_openapi_to_dict(self) if to_openapi_to_dict is not None: return json.dumps(to_jsonable_python(to_openapi_to_dict(self))) return json.dumps(to_jsonable_python(self.to_dict()))其内部__openapi_generator_modern_projection通过setattr与to_dict互相引用避免占住模型成员名基于self.model_dump(by_aliasTrue, exclude_noneTrue)并显式对metadata、spec、status调用子模型的转换保证输出为驼峰键、剔除None字段、可直接json.loads往返。模块里那对“互相验证函数引用”的_get_openapi_to_dictv1_stateful_set.py用于确认拿到的是生成代码自身的to_dict防止子类覆写后误伤从源码结构看这是为保证“继承的生成方法”与“投影方法”配对一致而设的防护。to_str()返回pprint.pformat(self.to_dict())__repr__直接复用因此print(sts)会输出格式化字典便于调试。5.3 相等性比较__eq__定义为仅当对方也是同类型且to_dict()相等时成立v1_stateful_set.py跨类型比较一律为False。写断言或去重逻辑时可以放心用。6. 在 aio 异步客户端中使用 V1StatefulSetkubernetes.aio与同步客户端kubernetes的模型、API 结构一一对应但调用是async/await的。异步示例可参照 examples_asyncio/list_pods.py 的骨架import asyncio from kubernetes.aio import client, config from kubernetes.aio.client.api_client import ApiClient async def main(): await config.load_kube_config() # 上下文管理器会自动关闭 http session async with ApiClient() as api: apps_v1 client.AppsV1Api(api) core_v1 client.CoreV1Api(api) # 1. 先创建 headless Servicespec.service_name 要求先存在 svc client.V1Service( api_versionv1, kindService, metadataclient.V1ObjectMeta(nameredis-test-svc), specclient.V1ServiceSpec( selector{app: redis}, cluster_ipNone, # headless typeClusterIP, ports[client.V1ServicePort(port6379, target_port6379)] )) await core_v1.create_namespaced_service(namespacedefault, bodysvc) # 2. 构造 V1StatefulSetaio 模型字段与同步版一致 template client.V1PodTemplateSpec( metadataclient.V1ObjectMeta(labels{app: redis}), specclient.V1PodSpec(containers[client.V1Container( namests-redis, imageredis, image_pull_policyIfNotPresent, ports[client.V1ContainerPort(container_port6379)])])) sts client.V1StatefulSet( api_versionapps/v1, kindStatefulSet, metadataclient.V1ObjectMeta(namestatefulset-redis), specclient.V1StatefulSetSpec( replicas3, service_nameredis-test-svc, selectorclient.V1LabelSelector(match_labels{app: redis}), templatetemplate, pod_management_policyOrderedReady, revision_history_limit10)) created await apps_v1.create_namespaced_stateful_set(namespacedefault, bodysts) print(created.to_str()) # 3. 更新镜像并 patch等价于触发滚动更新 live await apps_v1.read_namespaced_stateful_set(statefulset-redis, default) live.spec.template.spec.containers[0].image redis:6.2 await apps_v1.patch_namespaced_stateful_set( namestatefulset-redis, namespacedefault, bodylive) # 4. 回滚读取指定 ControllerRevision将其 data patch 回去 revs await apps_v1.list_namespaced_controller_revision(default) owned [r for r in revs.items if r.metadata.owner_references and r.metadata.owner_references[0].kind StatefulSet and r.metadata.owner_references[0].name statefulset-redis] target sorted(owned, keylambda r: r.revision)[0] cr await apps_v1.read_namespaced_controller_revision(target.metadata.name, default) await apps_v1.patch_namespaced_stateful_set( namestatefulset-redis, namespacedefault, bodycr.data) if __name__ __main__: asyncio.run(main())上述流程与同步版示例 examples/rollout-statefulset.py 完全对应先建 headless Service再建 StatefulSet改镜像触发滚动更新最后通过list_namespaced_controller_revisionowner_references找到目标修订版本并把controller_revision.data作为 patch body 实现回滚。aio 版本的两点差异API 实例需要传入ApiClient如client.AppsV1Api(api)且所有方法均为协程需要await建议在async with ApiClient() as api:上下文中运行退出时自动关闭底层 httpx session避免连接泄漏。此外构造时若用蛇形键名如{service_name: ...}传入 dict__preprocess_input_names会将其归一为驼峰键名因此from_dict同时兼容两种命名风格但未知字段会被extraforbid拒绝升级集群后拉取新字段前建议同步升级客户端版本。7. 小结参考文档 kubernetes.aio.client.models.v1_stateful_set.rst 是纯automodule页真实内容即 v1_stateful_set.py 中的 Pydantic 模型定义V1StatefulSet仅 5 个顶层字段但通过spec/status两个子模型覆盖了副本数、选择器、Headless Service 绑定、Pod 模板、PVC 模板、更新策略、序号起点、保留策略与完整状态观测模型统一采用“Python 蛇形名 线上驼峰 alias”的双向映射validate_by_name/alias双验证、extraforbid严格拒绝未知字段to_dict(serialize...)、to_json、from_dict分别覆盖本地调试、发往 API Server 的 payload 构造与响应反序列化三条路径在kubernetes.aio中使用时V1StatefulSet与同步版字段一致差异仅在 API 调用改为await且需注入ApiClient可参考 examples_asyncio/list_pods.py 的异步骨架与 examples/rollout-statefulset.py 的 StatefulSet 生命周期操作含基于 ControllerRevision 的回滚。赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐Kubernetes Python 客户端 V1APIServiceList 模型详解APIService 列表对象的字段、序列化与异步用法Kubernetes Python 客户端 V1APIServiceList 模型详解APIService 列表对象的字段、序列化与异步用法 V1APISer后端云原生容器编排Kubernetes Python 客户端 V1DaemonSetCondition 模型详解DaemonSet 状态条件的类型、字段与序列化用法Kubernetes Python 客户端 V1DaemonSetCondition 模型详解DaemonSet 状态条件的类型、字段与序列化用法 导读 V1后端云原生容器编排Kubernetes Python 异步客户端 V1Deployment 模型全解析从字段语义到序列化与实战Kubernetes Python 异步客户端 V1Deployment 模型全解析从字段语义到序列化与实战 导读 V1Deployment 是 Kubern后端云原生容器编排上一篇终极指南如何用StreamFX打造专业级OBS直播特效下一篇StreamFX完整指南零门槛打造专业级直播特效的终极教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考