Python kubernetes 客户端中 V1ValidatingAdmissionPolicyBindingList 模型详解:ValidatingAdmissionPolicyBinding 列表对象的字段结构与序列化

原创2026-10-09 12:43:281,923 阅读
文章标签:云原生容器编排集群管理后端

Python kubernetes 客户端中 V1ValidatingAdmissionPolicyBindingList 模型详解:ValidatingAdmissionPolicyBinding 列表对象的字段结构与序列化

本文围绕官方 Kubernetes Python 客户端(本仓库)异步模型模块中的 V1ValidatingAdmissionPolicyBindingList 展开,说明该列表对象包含哪些字段、字段在 Python 属性名与 API wire 名之间如何映射、以及它在 AdmissionRegistration v1 API 的 list/watch 调用中扮演什么角色。读完后,你将能够正确解析服务端返回的 ValidatingAdmissionPolicyBindingList JSON,构造合法的列表对象,并利用 to_dict/from_dict/from_json/to_json 等方法完成与 REST 响应的互转。

该文档对应的模块:一个由 OpenAPI 生成的 Pydantic 模型

仓库内文档 doc/source/kubernetes.aio.client.models.v1_validating_admission_policy_binding_list.rst 是通过 Sphinx automodule 指令为 kubernetes.aio.client.models.v1_validating_admission_policy_binding_list 模块自动生成 API 文档的入口。它不描述额外行为,而是让文档构建系统直接引用模块内所有公开成员(:members:)、继承关系(:show-inheritance:)以及无 docstring 的成员(:undoc-members:)。因此,理解该文档等价于理解模型源码 v1_validating_admission_policy_binding_list.py。

从源码文件头部的声明注释可以确认三点事实:

  • 该模型由 OpenAPI Generator 自动生成,基于 OpenAPI 文档版本 release-1.37,因此不应手工编辑(文件头部明确写有 Do not edit the class manually);
  • 该文件属于 kubernetes.aio.client.models 包,即异步客户端(aio)的模型层,与同步客户端 kubernetes.client.models 平行存在;
  • 类继承自 Pydantic 的 BaseModel(第 98 行 class V1ValidatingAdmissionPolicyBindingList(BaseModel)),字段校验、别名解析均由 Pydantic 完成。

模块 docstring 对资源本身的定义为:

ValidatingAdmissionPolicyBindingList is a list of ValidatingAdmissionPolicyBinding.

即它是 Kubernetes 资源 ValidatingAdmissionPolicyBinding 的标准 List 包装对象,对应 API 端点 GET /apis/admissionregistration.k8s.io/v1/validatingadmissionpolicies 之外的同级 binding 集合端点 /apis/admissionregistration.k8s.io/v1/validatingadmissionpolicybindings 的返回体。

字段结构与类型约束

V1ValidatingAdmissionPolicyBindingList 共声明四个字段(源码第 108–117 行),__properties 类变量记录其 wire 名顺序为 ["apiVersion", "items", "kind", "metadata"]:

Python 属性 wire(JSON)键 类型 是否必填 说明
api_version apiVersion Optional[StrictStr],默认 None 否 对象表示的版本化 schema 标识。服务端应把可识别的 schema 转换为最新的内部表示,并可能拒绝无法识别的值
items items List[V1ValidatingAdmissionPolicyBinding] 是(唯一无默认值的字段) PolicyBinding 对象列表
kind kind Optional[StrictStr],默认 None 否 表示 REST 资源的字符串值,CamelCase。服务端可从客户端请求的端点推断,不可更新。典型值为 ValidatingAdmissionPolicyBindingList
metadata metadata Optional[V1ListMeta],默认 None 否 列表元数据,含分页与版本信息

几个值得注意的实现细节:

  1. 唯一必填字段是 items。items: List[V1ValidatingAdmissionPolicyBinding] = Field(description="List of PolicyBinding.")(第 109 行)没有默认值,Pydantic 校验时若缺失会直接报错。kind、apiVersion、metadata 均可为 None。
  2. snake_case 与 camelCase 双向兼容。api_version 字段使用 validation_alias=AliasChoices("apiVersion", "api_version") 和 serialization_alias="apiVersion"(第 108 行),配合 model_config 中的 validate_by_name=True, validate_by_alias=True(第 141–147 行),意味着构造和解析时 api_version 与 apiVersion 两个名字都被接受,而序列化输出统一为 camelCase 的 apiVersion。这是整个 aio 模型包的通用约定,目的是既兼容 Python 命名习惯,又与 Kubernetes API 的 JSON 字段名严格对齐。
  3. extra="forbid 拒绝未知字段。model_config = ConfigDict(..., extra="forbid", ...)(第 145 行)表示传入 dict 中包含未声明的键时,model_validate 会抛出校验错误,而不是静默丢弃。这对防御"把单数对象当列表传"等误用很有价值。
  4. openapi_types / attribute_map / __properties 三个类变量是生成器保留的元数据(第 112–125 行),分别给出每个字段的 Python 类型标注、Python 名到 JSON 名的映射、以及 wire 名列表。它们不参与 Pydantic 校验,但常被上层工具(如 OpenAPI 生成的 API 类做响应反序列化)读取。

关联模型:items 中的元素结构

items 的每个元素是 V1ValidatingAdmissionPolicyBinding。从该模型 docstring 可以确认其语义:ValidatingAdmissionPolicyBinding 将 ValidatingAdmissionPolicy 与参数化资源绑定起来;对于某个准入请求,每个 binding 会触发其 policy 被评估 N 次(不使用 params 时 N=1,否则 N 为 binding 选中的参数数量)。其字段为:

  • api_version / kind:可选字符串;
  • metadata: Optional[V1ObjectMeta]:对象元数据;
  • spec: V1ValidatingAdmissionPolicyBindingSpec:必填,绑定规格。

而 V1ValidatingAdmissionPolicyBindingSpec 进一步要求(源码第 108–111 行):

  • policy_name(wire 名 policyName):StrictStr,必填,引用一个 ValidatingAdmissionPolicy 的名字;引用资源不存在时该 binding 被视为无效并被忽略;
  • validation_actions(wire 名 validationActions):List[StrictStr],必填,声明校验失败如何执行。合法取值为 "Deny"(拒绝请求)、"Warn"(在 HTTP 299 Warning 头中报告)、"Audit"(写入审计事件,附带 validation.policy.admission.k8s.io/validation_failure 注解);"Deny" 与 "Warn" 不可同时使用;
  • match_resources(wire 名 matchResources):可选,V1MatchResources,约束哪些请求匹配该 binding;
  • param_ref(wire 名 paramRef):可选,V1ParamRef,指向参数化资源的引用。

因此,一个最小可用的列表对象至少要有非空的 items,且每个 item 的 spec 必须携带 policyName 和 validationActions。

序列化与反序列化:to_dict / from_dict / to_json / from_json

模型提供了一组对称的转换方法(源码第 150–258 行),这是它与服务端 JSON 交互的核心 API。

to_dict 的双模式

to_dict(self, serialize: bool = False)(第 185–192 行)返回全部字段的 dict。serialize 参数决定键名风格:

  • serialize=False(默认):返回公共 Python 名,即 api_version 为键,嵌套模型递归调用其 to_dict(serialize=...)(经由 _to_legacy_value / _to_legacy_item 辅助函数,第 60–79 行);
  • serialize=True:返回 wire 名(apiVersion 等),用于直接映射到 HTTP 响应/请求体。

注意 _to_legacy_value 的实现:它对 list 只转换直接元素、对 dict 只转换直接值(源码注释引用了 openapi-generator 的 python-legacy 模板行为),这与旧版同步客户端的序列化语义保持兼容。

to_json 走 OpenAPI 投影路径

to_json()(第 173–178 行)优先调用模块级函数 _get_openapi_to_dict(self) 找到的"现代投影"函数,再经 pydantic_core.to_jsonable_python 与 json.dumps 输出。该投影函数即类体末尾(第 194–233 行)通过 setattr 互相绑定的 __openapi_generator_modern_projection 与 to_dict:

  • 它以 model_dump(by_alias=True, exclude_none=True) 为基础,只输出非 None 字段(docstring 明确说明:None 仅对初始化时显式设置的可选字段保留,其余 None 字段被忽略);
  • 它会显式重写 items 与 metadata 两个嵌套字段,对每个 item 递归调用其各自的 to_dict,保证嵌套对象也被展开为 plain dict 而非模型实例。

_get_openapi_to_dict(第 33–57 行)通过"双向函数引用"(to_dict 与投影函数互相持有 __openapi_generator_to_dict 属性)来识别哪些对象携带了生成器方法,同时拒绝被装饰器复制了函数属性的伪造覆盖——这是一种防止子类/猴子补丁破坏序列化契约的防护设计。

from_dict 的递归构造

from_dict(cls, obj)(第 235–258 行)是反序列化入口:

  1. obj is None 时返回 None;
  2. 先经 __preprocess_input_names(第 127–139 行)做键名预处理:若 dict 中缺 apiVersion 而有 api_version,则改名并移除 api_version 键——这是 snake_case 输入的兜底通道;
  3. 然后按字段逐一 model_validate:items 列表中的每个元素都会调用 V1ValidatingAdmissionPolicyBinding.from_dict(_item) 递归构造(第 254 行),metadata 则调用 V1ListMeta.from_dict(第 256 行)。

配套的 from_json(cls, json_str)(第 180–183 行)只是 from_dict(json.loads(json_str)) 的便捷封装。

to_str() 与 __repr__(第 150–156 行)通过 pprint.pformat(self.to_dict()) 给出可读的 Python 风格打印;__eq__/__ne__(第 158–170 行)基于 to_dict() 的深比较,且类型不同直接判不等。

metadata:V1ListMeta 提供分页信息

metadata 字段类型 V1ListMeta 是 Kubernetes 所有 List 对象的标准元数据,从源码可见其包含:

  • var_continue(wire 名 continue,第 108 行):设置了 limit 且服务端还有更多数据时给出的不透明分页 token,可用于继续拉取下一批对象;
  • resource_version(wire 名 resourceVersion):标识本次列表快照的服务端版本,对 watch 续接至关重要;
  • self_link:已弃用的遗留只读字段;
  • 此外 __properties 中还包含 remainingItemCount、shardInfo。

实际调用场景:list_validating_admission_policy_binding

V1ValidatingAdmissionPolicyBindingList 在客户端中不是孤立对象,它是 AdmissionRegistration v1 异步 API 的返回类型。在 admissionregistration_v1_api.py 中,list_validating_admission_policy_binding(第 9686 行起)的签名声明返回值类型为 V1ValidatingAdmissionPolicyBindingList,其参数序列化阶段(第 9667–9680 行)请求的资源路径为:

GET /apis/admissionregistration.k8s.io/v1/validatingadmissionpolicies... 对应的 binding 集合

该方法支持完整的 list/watch 查询参数,均可选:pretty、_continue、field_selector、label_selector、limit、resource_version、resource_version_match、send_initial_events、shard_selector、timeout_seconds、watch 等(第 9688–9699 行),并声明 BearerToken 认证(第 9663–9665 行)。同一 API 类中还提供了 create_validating_admission_policy_binding(请求体/返回值为单数 V1ValidatingAdmissionPolicyBinding)、delete_*、patch_*、read_* 等成套方法——List 模型只出现在 list/watch 路径上,这与 Kubernetes API 约定一致。

典型使用流程(基于源码中方法签名可验证):

import asyncio
from kubernetes.aio.client import ApiClient
from kubernetes.aio.client.models import (
    V1ObjectMeta,
    V1ValidatingAdmissionPolicyBinding,
    V1ValidatingAdmissionPolicyBindingSpec,
)
from kubernetes.config import load_kube_config


async def main():
    load_kube_config()
    async with ApiClient() as api_client:
        api = api_client.get_api('admissionregistration_v1_api.AdmissionRegistrationV1Api')
        # list/watch 返回 V1ValidatingAdmissionPolicyBindingList
        binding_list = await api.list_validating_admission_policy_binding(
            label_selector="app=my-policy-controller",
            limit=100,
        )
        print(binding_list.kind)          # 通常为 "ValidatingAdmissionPolicyBindingList"
        for item in binding_list.items:   # 每项为 V1ValidatingAdmissionPolicyBinding
            print(item.metadata.name, item.spec.policy_name, item.spec.validation_actions)
        if binding_list.metadata and binding_list.metadata.var_continue:
            # 存在更多数据,用 continue token 拉取下一页
            print("has more:", binding_list.metadata.var_continue)


asyncio.run(main())

也可以直接从 JSON 构造/还原对象,验证序列化闭环:

from kubernetes.aio.client.models.v1_validating_admission_policy_binding_list import (
    V1ValidatingAdmissionPolicyBindingList as L,
)

payload = {
    "apiVersion": "admissionregistration.k8s.io/v1",
    "kind": "ValidatingAdmissionPolicyBindingList",
    "metadata": {"resourceVersion": "123456"},
    "items": [
        {
            "apiVersion": "admissionregistration.k8s.io/v1",
            "kind": "ValidatingAdmissionPolicyBinding",
            "metadata": {"name": "my-binding"},
            "spec": {
                "policyName": "my-policy",
                "validationActions": ["Deny"],
                "matchResources": {"namespaceSelector": {}},
            },
        }
    ],
}

obj = L.from_json(__import__("json").dumps(payload))   # 或 L.from_dict(payload)
print(obj.to_dict(serialize=True))                      # 键名回到 camelCase
print(obj.to_json())                                     # 非 None 字段以 wire 名输出

上述示例中的字段组合(spec.policyName、spec.validationActions、matchResources)均可在 v1_validating_admission_policy_binding_spec.py 的 attribute_map 中逐一核对;match_resources.namespaceSelector 等更深层字段定义在 V1MatchResources 模型中。

小结与适用边界

  • V1ValidatingAdmissionPolicyBindingList 是 admissionregistration.k8s.io v1 ValidatingAdmissionPolicyBinding 集合端点的响应模型,四个字段中仅 items 必填;
  • 它是 OpenAPI Generator 基于 release-1.37 生成的 Pydantic v2 模型:extra="forbid" 严格校验、camelCase/snake_case 双别名输入、统一 camelCase 输出;
  • to_dict(serialize=...)、to_json、from_dict、from_json 构成与服务端 JSON 的完整互转链路,metadata(V1ListMeta)承载 continue/resourceVersion 等分页与 watch 状态;
  • 该模型及所在 API 类均位于 kubernetes.aio.client 包内,面向 asyncio 场景;同步调用应使用 kubernetes.client 下的对应同名模型。由于模型由生成器产出,升级客户端版本时应以新版本生成结果为准,而非手工修补模型代码。
登录后查看全文
python