深入解析 Kubernetes Python 客户端中的 V1PodDisruptionBudgetList:PDB 列表模型的字段、序列化与实战用法

原创2026-10-09 13:37:461,942 阅读
文章标签:云原生后端

深入解析 Kubernetes Python 客户端中的 V1PodDisruptionBudgetList:PDB 列表模型的字段、序列化与实战用法

本指南以 doc/source/kubernetes.aio.client.models.v1_pod_disruption_budget_list.rst 所定义的 API 文档主题为核心,围绕 kubernetes.aio.client.models.v1_pod_disruption_budget_list 模块展开。该模块由 OpenAPI Generator 依据 Kubernetes OpenAPI 规范(release-1.37)自动生成,为 policy/v1 组下的 PodDisruptionBudget 列表类资源提供类型化数据模型。读完本文,你将掌握 V1PodDisruptionBudgetList 的全部字段语义、序列化/反序列化机制,以及如何借助 PolicyV1Api 的 list 接口获取并解析 PDB 列表对象。

一、模型定位:PodDisruptionBudgetList 在客户端体系中的角色

V1PodDisruptionBudgetList 是 Kubernetes 官方 Python 客户端中用于表达“一组 PodDisruptionBudget(Pod 中断预算,简称 PDB)集合”的模型类。其类注释给出明确定义:

PodDisruptionBudgetList is a collection of PodDisruptionBudgets.

在 Kubernetes 中,PDB 用于限定任意时刻自愿驱逐(voluntary disruption)可影响的 Pod 数量下限/上限,保障应用在节点维护、集群升级等场景下的可用性。客户端通过 policy/v1 API 发起 list/watch 请求时,服务端返回的 JSON 响应体正是 V1PodDisruptionBudgetList 结构。因此,该模型是所有 PDB 批量读取类操作的数据载体,是连接 Kubernetes API Server 与 Python 应用之间的关键数据契约。

该模型位于两个并行的命名空间下:

两个版本的字段与行为保持一致,本文以 kubernetes.aio.client.models 下的实现为分析主体。

二、类结构总览:继承自 Pydantic BaseModel 的现代模型

从源码可见,V1PodDisruptionBudgetList 直接继承自 pydantic.BaseModel(v1_pod_disruption_budget_list.py),并借助 typing_extensions.Self、collections.abc.Mapping 等类型基础设施构建。这是当前仓库生成的模型普遍采用的风格:Pydantic v2 类型系统保证字段校验、别名解析与序列化能力。

类的核心元数据包含两组类属性:

  • openapi_types:字段名到 OpenAPI 类型的映射,例如 items 对应 List[V1PodDisruptionBudget];
  • attribute_map:Python 字段名到 JSON 线上字段名(wire name)的映射,例如 api_version → apiVersion;
  • __properties:声明全部线上字段名 ["apiVersion", "items", "kind", "metadata"],用于统一校验与序列化投影。

model_config 的配置同样值得注意(v1_pod_disruption_budget_list.py):

model_config = ConfigDict(
    validate_by_name=True,
    validate_by_alias=True,
    validate_assignment=True,
    extra="forbid",
    protected_namespaces=(),
)
  • validate_by_name=True:允许按 Python 字段名(snake_case)传参校验;
  • validate_by_alias=True:同时允许按别名(camelCase 的 apiVersion)传参;
  • validate_assignment=True:实例创建后的属性赋值同样触发校验;
  • extra="forbid":拒绝未知字段,防止拼写错误悄悄通过。

三、字段详解:四项属性构成完整的列表资源

V1PodDisruptionBudgetList 共有四个字段(v1_pod_disruption_budget_list.py):

Python 字段 JSON 字段(wire name) 类型 必填 说明
api_version apiVersion Optional[StrictStr] 否 对象表示所用的版本化 schema。服务端会把可识别的 schema 转换为最新内部值,并可能拒绝无法识别的值
items items List[V1PodDisruptionBudget] 是 PDB 对象列表,是列表资源的正文主体
kind kind Optional[StrictStr] 否 REST 资源类型的字符串标识,服务端可从客户端请求的端点推断,不可更新,CamelCase 格式,此处固定为 PodDisruptionBudgetList
metadata metadata Optional[V1ListMeta] 否 列表级元数据,记录续传令牌、资源版本等分页与一致性信息

其中 items 是唯一必填字段(声明时无默认值),任何缺少 items 的构造或反序列化都会触发 Pydantic 校验错误。

3.1 元素类型:V1PodDisruptionBudget

items 列表中的每个元素都是 v1_pod_disruption_budget.py 定义的 V1PodDisruptionBudget,其字段为:

  • apiVersion / kind:资源标识;
  • metadata(V1ObjectMeta):对象的名称、命名空间、标签、注解等标准元数据;
  • spec(V1PodDisruptionBudgetSpec):预算规则定义;
  • status(V1PodDisruptionBudgetStatus):由 disruption controller 回填的运行状态。

其中 V1PodDisruptionBudgetSpec(v1_pod_disruption_budget_spec.py)是理解 PDB 语义的关键:

  • maxUnavailable(int | str):驱逐后允许最多不可用的 Pod 数,可与 minAvailable 二选一;指定为 0 可阻止所有自愿驱逐;
  • minAvailable(int | str):驱逐后仍必须保持可用的 Pod 数,可用百分比(如 "100%")表达;
  • selector(V1LabelSelector):标签选择器,圈定受该预算约束的 Pod 集合;
  • unhealthyPodEvictionPolicy(str):定义不健康 Pod 的驱逐判定策略,合法值为 IfHealthyBudget(默认)与 AlwaysAllow。

而 V1PodDisruptionBudgetStatus(v1_pod_disruption_budget_status.py)则包含 currentHealthy、desiredHealthy、disruptionsAllowed、expectedPods、disruptedPods、observedGeneration 与 conditions 等运行期指标,用于评估预算当前是否允许继续驱逐。

3.2 列表元数据:V1ListMeta

metadata 字段由 v1_list_meta.py 中的 V1ListMeta 承载,它是所有 list 类型资源共用的“合成资源元数据”(synthetic resources must have, including lists)。其字段包括:

  • continue(_continue):分页续传令牌。当请求设置了 limit 而服务端还有更多数据时返回;客户端应将其原样传给下一次 list 请求以获取后续分片;
  • remainingItemCount(int):当前响应未包含的剩余条目估算值,用于估算集合规模,客户端不应依赖其精确性(v1.15 之前的服务端不设置该字段);
  • resourceVersion(str):服务端内部版本标识,客户端应将其视为不透明字符串原样回传,用于一致性与并发控制;
  • selfLink(str):已废弃的只读字段,系统不再填充;
  • shardInfo(V1ShardInfo):分片信息,服务于新的分片 list/watch 机制。

值得留意的是 V1ListMeta 通过 @model_validator(mode="wrap") 与 __preprocess_input_names 做了输入名称预处理(v1_list_meta.py):同时传入 continue 与 _continue 会抛出 ValueError,仅传入 _continue 时则自动归一化为 continue,从而兼顾 Python 关键字冲突与线上协议兼容。

四、序列化与反序列化:模型与 JSON 的双向转换

V1PodDisruptionBudgetList 提供了多组方法完成模型对象与 JSON/dict 的互转(v1_pod_disruption_budget_list.py):

4.1 序列化输出

  • to_str() / __repr__():返回 pprint.pformat(self.to_dict()) 的可读字符串,便于日志打印与调试;
  • to_dict(serialize=False):返回全部声明字段的 dict,默认使用 Python 风格字段名(snake_case),serialize=True 时改用线上 wire 名(camelCase);
  • to_json():返回 JSON 字符串,始终使用别名(apiVersion 等线上字段名)输出;
  • __eq__ / __ne__:基于 to_dict() 结果比较模型相等性。

4.2 反序列化输入

  • from_dict(obj):从 dict 构建实例。内部先调用 __preprocess_input_names 将 api_version 归一化为 apiVersion,再递归调用 V1PodDisruptionBudget.from_dict 解析每个 items 元素、V1ListMeta.from_dict 解析 metadata;
  • from_json(json_str):等价于 from_dict(json.loads(json_str)),直接从 JSON 字符串构建模型。

4.3 别名与隐藏存储名的处理机制

源码中的 __preprocess_input_names(v1_pod_disruption_budget_list.py)体现了一个通用约定:模型允许以 snake_case 的 Python 字段名(如 api_version)构造对象,并在进入 Pydantic 校验前统一改写为线上别名(apiVersion)。同理,V1ListMeta 内部以 var_continue 作为底层存储名,通过 property 暴露 _continue 访问接口,避免与 Python 关键字 continue 冲突——这一设计在 v1_list_meta.py 中体现得尤为典型。

此外,源码通过 _get_openapi_to_dict 与 _to_legacy_value / _to_openapi_value 等辅助函数(v1_pod_disruption_budget_list.py)在“现代 Pydantic 投影”与“legacy 序列化行为”之间建立双向等价引用,保证继承自生成器的 to_dict 行为一致且可被正确识别,这是仓库针对生成代码做的一层兼容性收敛。

五、实战:通过 policy/v1 API 获取并解析 PDB 列表

V1PodDisruptionBudgetList 的典型消费场景是 PolicyV1Api 的 list 类方法。在 kubernetes/aio/client/api/policy_v1_api.py 中有三个成组的异步方法(每个方法另附 _with_http_info 与 _without_preload_content 变体):

  • list_namespaced_pod_disruption_budget(...)(policy_v1_api.py):按命名空间列出 PDB,响应映射为 200 → V1PodDisruptionBudgetList;
  • list_pod_disruption_budget_for_all_namespaces(...)(policy_v1_api.py):跨全部命名空间列出 PDB,同样返回 V1PodDisruptionBudgetList。

list_namespaced_pod_disruption_budget 的核心参数(均可选,除 namespace 必填)包括:

参数 类型 作用
namespace str 必填,对象名称与鉴权作用域
pretty str 是否美化输出,默认 'false'
allow_watch_bookmarks bool 是否请求 BOOKMARK 类型 watch 事件
_continue str 分页续传令牌,来自上一响应的 metadata.continue
field_selector / label_selector str 按字段 / 标签过滤返回对象,默认返回全部
limit int 单次返回最大条数;更多数据时服务端在 metadata.continue 中给出续传令牌
resource_version / resource_version_match str 资源版本约束与匹配策略(建议设置 resourceVersionMatch)
send_initial_events bool 与 watch=true 配合,先发送集合当前状态的全量合成事件
shard_selector str 基于 CEL 表达式的分片选择器(alpha,需启用 ShardedListAndWatch feature gate)
timeout_seconds int list/watch 调用超时
watch bool 是否以流式 watch 返回 add/update/remove 变更通知
_request_timeout float 或 (float, float) 请求超时,可为总超时或(连接, 读取)二元组

下面是一段可直接运行的异步示例,演示如何获取指定命名空间与全集群的 PDB 列表,并遍历 items 输出预算状态:

import asyncio
from kubernetes import config
from kubernetes.aio.client.api import policy_v1_api
from kubernetes.aio.client.models.v1_pod_disruption_budget import V1PodDisruptionBudget


async def main() -> None:
    # 加载集群配置(集群外场景;集群内可使用 config.load_incluster_config())
    await config.load_kube_config()

    async with policy_v1_api.PolicyV1Api() as api:
        # 1) 列出指定命名空间下的 PDB
        ns_list = await api.list_namespaced_pod_disruption_budget(
            namespace="default",
            limit=100,                 # 开启分页,超限时 metadata.continue 给出续传令牌
            label_selector="app=web",  # 按标签过滤
        )
        print("namespace list kind:", ns_list.kind, "| apiVersion:", ns_list.api_version)
        print("resourceVersion:", ns_list.metadata.resource_version if ns_list.metadata else None)
        print("continue token:", ns_list.metadata._continue if ns_list.metadata else None)

        # 2) 列出全部命名空间下的 PDB
        all_list = await api.list_pod_disruption_budget_for_all_namespaces(
            field_selector="metadata.namespace=default"
        )

        # 3) 遍历列表元素,读取每个 PDB 的 spec 与 status
        for pdb in all_list.items:  # type: V1PodDisruptionBudget
            spec, status = pdb.spec, pdb.status
            if spec is None:
                continue
            print(
                f"PDB: {pdb.metadata.name if pdb.metadata else '?'} "
                f"| minAvailable={spec.min_available} maxUnavailable={spec.max_unavailable}"
            )
            if status is not None:
                print(
                    f"  -> currentHealthy={status.current_healthy} "
                    f"desiredHealthy={status.desired_healthy} "
                    f"disruptionsAllowed={status.disruptions_allowed} "
                    f"expectedPods={status.expected_pods}"
                )

        # 4) 序列化回 JSON(使用线上别名 apiVersion),以及从 JSON 反向构建
        raw_json = all_list.to_json()
        rebuilt = V1PodDisruptionBudgetList.from_json(raw_json)
        assert rebuilt == all_list


if __name__ == "__main__":
    asyncio.run(main())

上述代码中值得注意的调用细节:

  • metadata._continue 与 metadata.resource_version 配合可实现“一致快照”的分页遍历:客户端携带续传令牌反复请求直到 metadata.continue 为空;
  • to_json() 输出的是 apiVersion、items 等线上字段名,可直接作为后续创建/更新请求的负载;而 from_dict/from_json 则允许以 Python snake_case 或线上 camelCase 两种风格输入;
  • 若需要拿到完整的 HTTP 响应(状态码、响应头),可改用 list_namespaced_pod_disruption_budget_with_http_info,其返回类型为 ApiResponse[V1PodDisruptionBudgetList]。

同步客户端(非 asyncio)的用法完全一致,只需将导入路径中的 kubernetes.aio.client 换成 kubernetes.client,并把 async with 改为普通上下文管理器或直接实例化调用。

六、与测试及文档体系的关联

该模型的 API 文档页由 Sphinx 的 automodule 指令驱动(doc/source/kubernetes.aio.client.models.v1_pod_disruption_budget_list.rst),配合 :members:、:show-inheritance:、:undoc-members: 选项,构建时会自动把模块内所有成员(类、字段、方法)渲染进 doc/html 文档。仓库中与之对应的还有 kubernetes.client.models 下的同步版本,以及完整的 policy/v1 API 文档(doc/html/kubernetes.aio.client.api.policy_v1_api.html),可作为进一步查阅 PDB 相关接口的入口。

若要在本地验证本文涉及的导入与类型,可结合仓库根目录的 requirements.txt 安装依赖(含 pydantic),并参考 examples 目录中的异步示例(如 examples_asyncio/list_pods.py)了解 asyncio 客户端的通用使用范式。

七、小结

V1PodDisruptionBudgetList 虽然是一个由 OpenAPI Generator 生成的“纯数据”模型,但它承担了 PDB 批量读取场景中从 HTTP JSON 响应到强类型 Python 对象的全部转换职责。其四个字段(apiVersion、items、kind、metadata)与 Kubernetes 列表资源的通用约定一一对应,而 to_dict/to_json/from_dict/from_json 方法族保证了客户端在 snake_case 与 camelCase 两套命名体系之间无缝切换。结合 PolicyV1Api 的 list 方法、metadata.continue 分页令牌以及 V1PodDisruptionBudgetSpec/Status 的语义字段,开发者即可在同步或 asyncio 两种模式下稳健地完成 PDB 的采集、巡检与自动化运维。

登录后查看全文
python