Python kubernetes 客户端中 V1ValidatingAdmissionPolicyBindingList 模型详解:ValidatingAdmissionPolicyBinding 列表对象的字段结构与序列化
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 |
否 | 列表元数据,含分页与版本信息 |
几个值得注意的实现细节:
- 唯一必填字段是
items。items: List[V1ValidatingAdmissionPolicyBinding] = Field(description="List of PolicyBinding.")(第 109 行)没有默认值,Pydantic 校验时若缺失会直接报错。kind、apiVersion、metadata均可为None。 - 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 字段名严格对齐。 extra="forbid拒绝未知字段。model_config = ConfigDict(..., extra="forbid", ...)(第 145 行)表示传入 dict 中包含未声明的键时,model_validate会抛出校验错误,而不是静默丢弃。这对防御"把单数对象当列表传"等误用很有价值。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 行)是反序列化入口:
obj is None时返回None;- 先经
__preprocess_input_names(第 127–139 行)做键名预处理:若 dict 中缺apiVersion而有api_version,则改名并移除api_version键——这是 snake_case 输入的兜底通道; - 然后按字段逐一
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 v1ValidatingAdmissionPolicyBinding集合端点的响应模型,四个字段中仅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下的对应同名模型。由于模型由生成器产出,升级客户端版本时应以新版本生成结果为准,而非手工修补模型代码。