Kubernetes Python 客户端 V1PodDisruptionBudgetSpec 模型详解:PDB 弹性预算配置与序列化实战

原创2026-10-09 16:13:431,659 阅读
文章标签:云原生容器编排集群管理后端

Kubernetes Python 客户端 V1PodDisruptionBudgetSpec 模型详解:PDB 弹性预算配置与序列化实战

本文以 Kubernetes Python 客户端(kubernetes,官方 Python client library for kubernetes)中 kubernetes.aio.client.models.v1_pod_disruption_budget_spec 模型为讲解主线,深入剖析 PodDisruptionBudget(PDB)Spec 中 maxUnavailable、minAvailable、selector、unhealthyPodEvictionPolicy 四个核心字段的语义、默认值与互斥约束,并结合 policy_v1_api 的增删改查调用链和模型源码的 Pydantic 校验/序列化实现,帮助读者掌握如何在异步(aio)客户端中正确构造、提交、解析和序列化 PDB 配置。

PodDisruptionBudget 是 Kubernetes 中保障业务在主动运维操作(节点维护、滚动升级、应用驱逐等)期间不中断的关键机制。本指南将带你从模型源码出发,完整掌握 V1PodDisruptionBudgetSpec 的每个字段、它们如何与 V1LabelSelector、V1PodDisruptionBudget 及其 Status 协作,并给出可复制的异步 API 调用示例与模型序列化/反序列化用例。

PDB 是什么:先理解 Spec 的用途边界

PodDisruptionBudget(PDB)用于限制因**自愿中断(voluntary disruptions)**而同时不可用的 Pod 数量上限,例如节点维护(drain)、应用滚动更新、人工驱逐等场景。PDB 不阻止中断本身,而是通过 API Server 的 Eviction 子资源(eviction subresource) 在驱逐前校验预算,阻止会让可用 Pod 数量跌破预算的驱逐请求。

在 Kubernetes Python 客户端中,PDB 资源被建模为一组相互关联的模型类(均位于 kubernetes/aio/client/models/ 目录,基于 OpenAPI Generator 从 release-1.37 的 OpenAPI 文档生成,由 Pydantic v2 驱动):

模型类 模块路径 职责
V1PodDisruptionBudget kubernetes.aio.client.models.v1_pod_disruption_budget PDB 顶层资源对象,包含 metadata、spec、status
V1PodDisruptionBudgetSpec kubernetes.aio.client.models.v1_pod_disruption_budget_spec 本文主角:定义预算策略(可驱逐多少、选择哪些 Pod、不健康 Pod 如何处理)
V1PodDisruptionBudgetStatus kubernetes.aio.client.models.v1_pod_disruption_budget_status 控制器计算出的实时状态(当前健康数、允许驱逐数等)
V1PodDisruptionBudgetList kubernetes.aio.client.models.v1_pod_disruption_budget_list PDB 的集合对象,用于 list 系列 API 的返回解析

对象关系可概括为:V1PodDisruptionBudget.spec 的类型即 V1PodDisruptionBudgetSpec(见 v1_pod_disruption_budget.py),V1PodDisruptionBudget.spec.selector 的类型即 V1LabelSelector(见 v1_pod_disruption_budget_spec.py)。因此,要正确使用 PDB,首先就要吃透 Spec 的每个字段。

V1PodDisruptionBudgetSpec 模型结构总览

V1PodDisruptionBudgetSpec 继承自 Pydantic 的 BaseModel(见 v1_pod_disruption_budget_spec.py),共声明 4 个字段。其类级元数据如下(同一文件 L111-L124):

openapi_types: ClassVar[Dict[str, str]] = {
    "max_unavailable": "object",          # 可接受 int(绝对值)或 str(百分比)
    "min_available": "object",            # 同上,int 或百分比字符串
    "selector": "V1LabelSelector",
    "unhealthy_pod_eviction_policy": "str",
}

attribute_map: ClassVar[Dict[str, str]] = {
    "max_unavailable": "maxUnavailable",
    "min_available": "minAvailable",
    "selector": "selector",
    "unhealthy_pod_eviction_policy": "unhealthyPodEvictionPolicy",
}

attribute_map 展示了 Python 属性名(snake_case)与 Kubernetes 线上 JSON 字段名(camelCase)的映射:max_unavailable ↔ maxUnavailable、min_available ↔ minAvailable、unhealthy_pod_eviction_policy ↔ unhealthyPodEvictionPolicy。这也是模型在提交给 API Server 时序列化所依据的线协议命名。

四个字段逐一解析

1. max_unavailable:最多允许同时不可用的 Pod 数量

类型为 Optional<a href="https://link.gitcode.com/i/57b2740bc621ddcb8178415390dba142" target="_blank">StrictInt | StrictStr],默认 None([源码 L107)。语义:驱逐后,被 selector 选中的 Pod 中,最多有 maxUnavailable 个处于不可用状态(且统计时不包含被驱逐的那个 Pod 本身)。

  • 可以指定绝对数量,如 1;
  • 也可以指定百分比字符串,如 "50%",按选择到的 Pod 总数向下取整计算;
  • 文档明确给出的边界示例:设置为 0 可以阻止所有自愿驱逐;
  • 与 min_available 互斥(mutually exclusive),二者只能设置其一。

2. min_available:驱逐后必须仍然可用的最少 Pod 数量

类型同样为 Optional<a href="https://link.gitcode.com/i/b0e86d64d6a55f3ef758e172ad70936e" target="_blank">StrictInt | StrictStr],默认 None([源码 L108)。语义:驱逐后,被 selector 选中的 Pod 中,至少有 minAvailable 个仍然可用(统计时不包含被驱逐的那个 Pod)。

  • 支持绝对数量或百分比,如 "100%"——文档给出的例子明确说明,设置 "100%" 可以阻止所有自愿驱逐;
  • 与 max_unavailable 互斥。

3. selector:选择受预算约束的 Pod

类型为 Optional<a href="https://link.gitcode.com/i/4a0d875589ab373ba559dafea0f06a7b" target="_blank">V1LabelSelector],默认 None([源码 L109)。它决定哪些 Pod 被纳入该 PDB 的统计范围。底层复用 V1LabelSelector 模型,后者包含两个字段:

  • match_labels:{key, value} 字典,等价于一个 operator 为 In 的 matchExpressions 条件;
  • match_expressions:V1LabelSelectorRequirement 列表,多个条件之间是 AND 关系。

当一个标签选择器同时设置 matchLabels 与 matchExpressions 时,二者结果取交集;空选择器匹配所有对象,null 选择器不匹配任何对象。

4. unhealthy_pod_eviction_policy:不健康 Pod 的驱逐策略

类型为 Optional<a href="https://link.gitcode.com/i/4e81539dc97839e379485c10ed393845" target="_blank">StrictStr],默认 None([源码 L110)。该字段定义“不健康 Pod 何时可被考虑驱逐”,当前实现将“健康 Pod”定义为拥有 status.conditions 中 type="Ready", status="True" 条件的 Pod。合法取值如下:

取值 语义
IfHealthyBudget(默认行为,未指定时采用) 尚未健康的运行中 Pod(status.phase="Running")仅在受保护应用未被打断(status.currentHealthy >= status.desiredHealthy)时才允许被驱逐;健康 Pod 始终受 PDB 约束
AlwaysAllow 所有尚未健康的运行中 Pod 都被视为“已中断”,无论 PDB 标准是否满足都可被驱逐;注意:被打断应用的这类 Pod 可能没有机会变为健康,健康 Pod 仍受 PDB 约束

源码注释同时强调:未来可能新增更多策略,客户端在遇到不认识的策略值时,应禁止驱逐不健康 Pod(在做出驱逐决策时对未知策略持保守态度)。

模型级校验配置

V1PodDisruptionBudgetSpec 的 model_config(源码 L146-L152)说明了生成模型的统一行为:

model_config = ConfigDict(
    validate_by_name=True,
    validate_by_alias=True,
    validate_assignment=True,
    extra="forbid",
    protected_namespaces=(),
)
  • validate_by_name=True 与 validate_by_alias=True:构造对象时既接受 snake_case(如 min_available)也接受 camelCase 别名(如 minAvailable)作为输入;每个字段通过 validation_alias=AliasChoices("maxUnavailable", "max_unavailable") 声明了双别名输入(见 源码 L107-L110)。
  • validate_assignment=True:对构造后的属性赋值也会即时校验类型。
  • extra="forbid":传入未声明字段会直接报错,防止拼写错误悄悄混入请求体。
  • serialization_alias:输出时统一使用 camelCase 的线上字段名。

max_unavailable / min_available 之所以是 StrictInt | StrictStr,正是为了同时兼容“绝对数量”与“百分比字符串”两种 Kubernetes 合法输入——这也与上游 OpenAPI 定义中该字段为 IntOrString 类型的事实一致。

从 Spec 到完整 PDB:模型组合与构建示例

在实际调用 API 前,需要把 Spec 组装进完整的 V1PodDisruptionBudget。下面是一个以 minAvailable + matchLabels 为主、并补充 unhealthyPodEvictionPolicy 的构造示例:

from kubernetes.aio.client.models import (
    V1LabelSelector,
    V1ObjectMeta,
    V1PodDisruptionBudget,
    V1PodDisruptionBudgetSpec,
)

spec = V1PodDisruptionBudgetSpec(
    min_available="100%",                      # 等价写法:minAvailable="100%"
    selector=V1LabelSelector(
        match_labels={"app": "web-frontend"},  # 选择 app=web-frontend 的 Pod
    ),
    unhealthy_pod_eviction_policy="AlwaysAllow",
)

pdb = V1PodDisruptionBudget(
    api_version="policy/v1",
    kind="PodDisruptionBudget",
    metadata=V1ObjectMeta(name="web-frontend-pdb", namespace="default"),
    spec=spec,
)

# 打印人类可读表示
print(pdb.to_str())

这里演示了三层要点:Spec 内 selector 嵌套 V1LabelSelector;Spec 作为 V1PodDisruptionBudget.spec 嵌入;顶层对象还需 api_version、kind、metadata。其中 kind 与 api_version 的字段描述同样来自源码(见 v1_pod_disruption_budget.py)。

值得注意:V1PodDisruptionBudgetSpec 的 to_str() / __repr__ 会调用 to_dict() 输出(见 源码 L155-L160),且对象相等性比较也基于 to_dict() 结果(L163-L175),因此调试与断言时行为是确定性的。

使用 PolicyV1Api 提交与查询 PDB

Spec 与对象模型最终要交给 API 层使用。在异步(aio)客户端中,PDB 的所有 CRUD 操作都集中在 kubernetes.aio.client.PolicyV1Api(源码位于 kubernetes/aio/client/api/policy_v1_api.py)。围绕 PDB 的核心方法包括:

  • create_namespaced_pod_disruption_budget(namespace, body, ...)
  • delete_namespaced_pod_disruption_budget(...) / delete_collection_namespaced_pod_disruption_budget(...)
  • list_namespaced_pod_disruption_budget(namespace, ...)(返回 V1PodDisruptionBudgetList)
  • patch_namespaced_pod_disruption_budget(...) / replace_namespaced_pod_disruption_budget(...)
  • read_namespaced_pod_disruption_budget(...)

从源码看,create_namespaced_pod_disruption_budget 的签名(policy_v1_api.py L65-L151)以 body: V1PodDisruptionBudget 为必填请求体,返回类型为 V1PodDisruptionBudget,响应码 200/201/202 均映射为该模型。此外还支持 pretty、dry_run("All" 时只走流程不持久化)、field_manager、field_validation(Ignore / Warn / Strict)等 Kubernetes 标准参数。

一个完整的异步调用示例(需依赖 asyncio 与集群 kubeconfig,参考 examples_asyncio/ 中的用法):

import asyncio
from kubernetes import config
from kubernetes.aio import client as aio_client
from kubernetes.aio.client.models import (
    V1LabelSelector,
    V1ObjectMeta,
    V1PodDisruptionBudget,
    V1PodDisruptionBudgetSpec,
)

async def create_pdb():
    await config.load_kube_config()  # 实际 async 客户端下请使用对应配置加载方式
    async with aio_client.ApiClient() as api_client:
        api = aio_client.PolicyV1Api(api_client)
        body = V1PodDisruptionBudget(
            api_version="policy/v1",
            kind="PodDisruptionBudget",
            metadata=V1ObjectMeta(name="web-frontend-pdb"),
            spec=V1PodDisruptionBudgetSpec(
                max_unavailable=1,
                selector=V1LabelSelector(match_labels={"app": "web-frontend"}),
            ),
        )
        created = await api.create_namespaced_pod_disruption_budget(
            namespace="default", body=body
        )
        print(created.to_dict())

asyncio.run(create_pdb())

这个例子同时覆盖了 max_unavailable=1(绝对数量)与 min_available="100%"(百分比字符串)两种 IntOrString 输入形态:无论哪种,StrictInt | StrictStr 字段类型都能正确通过 Pydantic 校验。

序列化、反序列化与别名机制

生成的模型内置了完整的 JSON/字典转换能力,这是与 API Server 通信的关键路径:

1. to_dict(serialize=False)(源码 L190-L197)

默认返回使用公开名(snake_case)的字典;当 serialize=True 时返回线上字段名(camelCase)。例如:

spec = V1PodDisruptionBudgetSpec(min_available="100%")
print(spec.to_dict())                  # {'min_available': '100%', ...}
print(spec.to_dict(serialize=True))    # {'minAvailable': '100%', ...}

嵌套的 selector 会递归调用其自身的 to_dict()(通过 _to_legacy_value 机制),保证整棵对象树都能转换。

2. to_json()(源码 L178-L183)

输出使用 camelCase 别名的 JSON 字符串,可直接作为请求体传给 API Server。

3. from_dict() / from_json()(源码 L185-L188、L234-L257)

从字典或 JSON 字符串反向构建模型。from_dict 会先执行 __preprocess_input_names(L126-L144),自动把 snake_case 键归一化为 camelCase,再对 selector 调用 V1LabelSelector.from_dict 递归解析,最后通过 model_validate 完成类型校验:

raw = {
    "maxUnavailable": "50%",
    "selector": {"matchLabels": {"app": "web-frontend"}},
}
spec = V1PodDisruptionBudgetSpec.from_dict(raw)
print(spec.max_unavailable)  # "50%"

这种“双名输入归一化 + 递归嵌套解析 + Pydantic 校验”的三段式流程,是理解所有生成模型 from_dict 的通路,V1PodDisruptionBudget(源码 L240-L264)与 V1PodDisruptionBudgetList(源码 L235-L258)都遵循同样的模式。

配套模型:Status 与 List 的字段意义

虽然本文核心是 Spec,但 PDB 的完整读写离不开与其配套的 Status 与 List:

V1PodDisruptionBudgetStatus(v1_pod_disruption_budget_status.py)包含控制器的计算结果:

  • current_healthy:当前健康 Pod 数量;
  • desired_healthy:期望的最少健康 Pod 数量;
  • disruptions_allowed:当前允许的驱逐数量——Spec 策略的最终落地结果;
  • expected_pods:被该预算统计的总 Pod 数;
  • disrupted_pods:API Server 已处理驱逐但 PDB 控制器尚未观察到删除的 Pod 映射(键为 Pod 名,值为处理时间);正常情况下应接近空,条目骤增通常意味着 Pod 删除异常;
  • observed_generation:最近一次被观测的 generation,仅当它等于 PDB 对象 generation 时其余状态字段才有效;
  • conditions:V1Condition 列表,控制器设置 DisruptionAllowed 条件,已知 reason 包括 SyncFailed(计算失败,不允许驱逐)、InsufficientPods(Pod 数已等于或低于预算所需,不允许驱逐)、SufficientPods(允许驱逐,数量见 disruptionsAllowed)。

V1PodDisruptionBudgetList(v1_pod_disruption_budget_list.py)是 list_namespaced_pod_disruption_budget 的返回类型,items 为 List[V1PodDisruptionBudget](必填字段),metadata 为 V1ListMeta。

测试与验证:模型行为在仓库中的印证

仓库的生成 API 测试 kubernetes/test/test_generated_api.py 对模型序列化行为给出了直接证据:测试将 V1PodDisruptionBudgetSpec 与预期别名映射绑定,断言 ('max_unavailable', 'maxUnavailable') 与 ('min_available', 'minAvailable') 的 snake_case→camelCase 转换(见该文件 L337-L340)。这说明 attribute_map / to_dict(serialize=True) 的映射行为是经过测试验证的、稳定可依赖的。

此外,kubernetes/aio/client/ 下所有模型均由 OpenAPI Generator 从 scripts/swagger.json(对应 release-1.37)生成,因此模型字段、类型与上游 Kubernetes API 保持一致;如需对照线上字段定义,可查看仓库内的 scripts/swagger.json。

常见陷阱与最佳实践小结

  1. maxUnavailable 与 minAvailable 二选一:两者互斥,同时设置会被 API Server 拒绝。
  2. 百分比是字符串:"50%" 必须写成字符串,写数字 50 会被当成绝对数量,语义完全不同。
  3. unhealthyPodEvictionPolicy 默认 IfHealthyBudget:不设置时即采用该默认行为;设置 AlwaysAllow 可让不健康 Pod 更快被驱逐,但要接受“健康前被驱逐”的风险。
  4. selector 谨慎留空:None 选择器匹配不到任何 Pod,预算等于空转;而空标签选择器会匹配所有对象,两者语义不同。
  5. 利用 dry_run="All" 先验证:创建/更新 PDB 前可先用 dry-run 校验 Spec 是否合法,避免破坏线上预算。
  6. extra="forbid" 的防护:模型对未声明字段直接报错,拼写错误(如把 minAvailable 写成 minavailable)会在本地尽早暴露,而不是等到 API Server 报错。

延伸阅读

登录后查看全文
python