Kubernetes Python 客户端异步模型 V1CertificateSigningRequestList 详解：结构、序列化与 List 接口实战

• 后端
• 云原生
• 容器编排

本篇技术指南聚焦于 Kubernetes 官方 Python 客户端（本仓库kubernetes.aio异步客户端）中的集合模型V1CertificateSigningRequestList。该模型对应 Kubernetes 的 CertificateSigningRequest（证书签名请求）资源集合，是调用CertificatesV1Api.list_certificate_signing_request系列接口时返回结果的载体。读完本文，你将掌握该模型的全部字段语义、别名映射机制、序列化/反序列化 API 的正确用法，并能在同步与异步两种客户端下实现 CSR 列表查询、分页遍历与 watch 监听。

一、模型定位：CertificateSigningRequestList 在证书管理链路中的角色

在 Kubernetes 集群中，CertificateSigningRequest（CSR）是节点（kubelet）与应用获取 x509 证书的核心机制：客户端提交一个签名请求，经管理员审批（approve）后由签发器（signer）异步签发证书。而V1CertificateSigningRequestList就是这一资源的集合容器——Kubernetes API Server 在响应 list 类请求时返回的顶层对象，正如V1PodList之于 Pod、V1NodeList之于 Node。

该模型在仓库中的直接依据是：

• 文档骨架 doc/source/kubernetes.aio.client.models.v1_certificate_signing_request_list.rst：通过 Sphinxautomodule指令自动收集模块成员生成 API 文档；
• 模型实现 kubernetes/aio/client/models/v1_certificate_signing_request_list.py（异步版）与其结构完全一致的同步版 kubernetes/client/models/v1_certificate_signing_request_list.py；
• 生成的 Markdown 参考文档 kubernetes/aio/docs/V1CertificateSigningRequestList.md。

从源码头部的生成注释可以确认，该模型基于 OpenAPI 规范（release-1.37）由 OpenAPI Generator 生成，类定义在 v1_certificate_signing_request_list.py 第 98 行，继承pydantic.BaseModel，属于本客户端在 v1.x 基础上全面转向 Pydantic v2 模型的产物。

二、V1CertificateSigningRequestList 字段详解

先看模型的类定义（kubernetes/aio/client/models/v1_certificate_signing_request_list.py）中声明的四个字段：

与常规单对象模型（如V1CertificateSigningRequest）不同，items是唯一必填字段，而api_version/kind/metadata均为可选。这一点从from_dict的实现可以印证：items为None时会抛出校验错误，其余字段则宽容处理（kubernetes/aio/client/models/v1_certificate_signing_request_list.py）。

同时，源码中定义了类型映射元数据，方便上层代码做通用处理：

openapi_types: ClassVar[Dict[str, str]] = { "api_version": "str", "items": "List[V1CertificateSigningRequest]", "kind": "str", "metadata": "V1ListMeta" } attribute_map: ClassVar[Dict[str, str]] = { "api_version": "apiVersion", "items": "items", "kind": "kind", "metadata": "metadata" }

三、字段别名与驼峰/蛇形命名映射机制

Kubernetes API 的 JSON 字段使用驼峰命名（apiVersion），而 Python 约定使用蛇形命名（api_version）。该模型通过 Pydantic 的AliasChoices同时接受两种输入：

api_version: Optional[StrictStr] = Field( default=None, validation_alias=AliasChoices("apiVersion", "api_version"), serialization_alias="apiVersion", ... )

配合model_config中的配置（kubernetes/aio/client/models/v1_certificate_signing_request_list.py）：

model_config = ConfigDict( validate_by_name=True, validate_by_alias=True, validate_assignment=True, extra="forbid", protected_namespaces=(), )

其实际效果为：

• 输入宽容：构造对象时，无论传{"apiVersion": "certificates.k8s.io/v1"}还是{"api_version": "certificates.k8s.io/v1"}均可被识别；
• 赋值即校验：validate_assignment=True保证对已实例化对象重新赋值字段时同样触发类型校验；
• 拒绝未知字段：extra="forbid"意味着传入未声明的键会直接抛校验异常，避免静默吞掉拼写错误；
• __preprocess_input_names归一化：类方法会把api_version归一化为apiVersion，再交给model_validate处理（kubernetes/aio/client/models/v1_certificate_signing_request_list.py）。

这一机制意味着你可以放心地把kubectl get csr -o json的输出直接喂给模型，也能按 Python 风格手写 snake_case 字典。

四、序列化与反序列化 API 全景

模型提供了完整的双向转换方法，全部可以在 kubernetes/aio/client/models/v1_certificate_signing_request_list.py 中找到实现：

from_dict的实现还展示了子模型的递归构造方式——items里的每个元素调用V1CertificateSigningRequest.from_dict()，metadata调用V1ListMeta.from_dict()：

_obj = cls.model_validate({ "apiVersion": obj.get("apiVersion"), "items": [V1CertificateSigningRequest.from_dict(_item) for _item in obj["items"]] if obj.get("items") is not None else None, "kind": obj.get("kind"), "metadata": V1ListMeta.from_dict(obj["metadata"]) if obj.get("metadata") is not None else None })

此外，模块中还引入了_to_openapi_value、_get_openapi_to_dict等辅助函数，保证嵌套子模型在序列化时也走各自的to_dict()投影逻辑，从而保持"字段名只输出已设置的非 None 字段"这一行为（对应__openapi_generator_modern_projection的注释说明）。

一个典型的往返示例（与 kubernetes/aio/docs/V1CertificateSigningRequestList.md 中的用法一致）：

from kubernetes.aio.client.models.v1_certificate_signing_request_list import V1CertificateSigningRequestList # 从 JSON 字符串创建实例 csr_list = V1CertificateSigningRequestList.from_json( '{"apiVersion": "certificates.k8s.io/v1", "kind": "CertificateSigningRequestList", ' '"items": [{"metadata": {"name": "csr-example"}}]}' ) # 转成 dict（Python 字段名） d = csr_list.to_dict() # 序列化为 JSON（驼峰别名） print(csr_list.to_json()) # 从 dict 再次构造 back = V1CertificateSigningRequestList.from_dict(d) assert csr_list == back # 值比较

五、在 CertificatesV1Api 中的实际使用：list_certificate_signing_request

V1CertificateSigningRequestList最核心的使用场景是作为CertificatesV1Api.list_certificate_signing_request的返回值。该接口在异步客户端中的声明位于 kubernetes/aio/client/api/certificates_v1_api.py：方法签名返回类型即V1CertificateSigningRequestList，响应类型映射中'200': "V1CertificateSigningRequestList"；同步客户端的对应实现在 kubernetes/client/api/certificates_v1_api.py。

同步客户端示例

from kubernetes import client, config config.load_kube_config() # 或 config.load_incluster_config() api = client.CertificatesV1Api() csr_list: client.V1CertificateSigningRequestList = ( api.list_certificate_signing_request(limit=10) ) print(csr_list.kind, csr_list.api_version) for csr in csr_list.items: print(csr.metadata.name, csr.spec.signer_name if csr.spec else None)

异步（aio）客户端示例

异步客户端的使用模式可参考 kubernetes/aio/README.md 中ApiClient的上下文管理器约定——API 实例可用async with托管，或显式await api_instance.close()：

import asyncio import kubernetes.aio.client as k8s async def list_csrs(): async with k8s.ApiClient() as api_client: api = k8s.CertificatesV1Api(api_client) csr_list: k8s.V1CertificateSigningRequestList = ( await api.list_certificate_signing_request(limit=10) ) for csr in csr_list.items: print(csr.metadata.name, csr.spec.signer_name if csr.spec else None) asyncio.run(list_csrs())

list_certificate_signing_request还支持丰富的查询参数（同步/异步签名一致，见 kubernetes/aio/client/api/certificates_v1_api.py 的 docstring），常用参数包括：

• pretty：是否美化输出；
• label_selector/field_selector：按标签/字段过滤，默认返回全部；
• limit：单次返回的最大条目数；
• _continue：分页续传令牌；
• resource_version/resource_version_match：对 list 请求做资源版本约束；
• timeout_seconds：list/watch 调用的超时；
• watch：是否以 watch 流方式监听变更。

六、分页与 watch：利用 metadata 字段做增量拉取

列表资源一大常见痛点是数据量大时的分页。V1ListMeta为此提供了专门字段（kubernetes/aio/client/models/v1_list_meta.py）：

• continue（属性_continue，内部存储var_continue）：当设置了limit且服务端还有更多数据时返回的不透明令牌，可用于下一次请求；
• remaining_item_count：后续未被本页包含的条目数，仅用于估算集合规模，客户端不应依赖其精确性；
• resource_version：标识对象内部版本的只读字符串，需原样回传给服务端，常用于并发控制与一致性检查；
• self_link：已废弃的只读遗留字段；
• shard_info：分片列表（alpha 特性ShardedListAndWatch）相关的分片信息。

借助metadata._continue即可实现完整的分页遍历（注意模型底部通过setattr安装了_continue转发属性，kubernetes/aio/client/models/v1_list_meta.py）：

from kubernetes import client, config config.load_kube_config() api = client.CertificatesV1Api() token = None page = 0 while True: page += 1 resp = api.list_certificate_signing_request(limit=100, _continue=token) print(f"--- page {page}: {len(resp.items)} items ---") for csr in resp.items: print(csr.metadata.name, csr.spec.signer_name if csr.spec else None) token = resp.metadata._continue if resp.metadata else None if not token: # continue 为空说明没有更多数据 break

如果需要持续观察 CSR 的创建、审批、签发状态变化，还可以结合watch参数与仓库内的 watch 模块（kubernetes/watch/）实现事件流监听：

from kubernetes import client, config, watch config.load_kube_config() w = watch.Watch() for event in w.stream(client.CertificatesV1Api().list_certificate_signing_request): csr = event["object"] print(event["type"], csr.metadata.name)

七、组成元素源码解读：V1CertificateSigningRequest 与 V1ListMeta

集合模型的价值取决于其成员的类型安全。items的每个元素是 kubernetes/aio/client/models/v1_certificate_signing_request.py 中定义的V1CertificateSigningRequest，它包含：

• spec（必填，V1CertificateSigningRequestSpec）：签名请求体；
• status（可选，V1CertificateSigningRequestStatus）：签发状态（如CertificateIssued）；
• metadata（可选，V1ObjectMeta）：对象元数据；
• api_version/kind：版本与种类标识。

从类 docstring 可以确认 CSR 的典型用途：kubelet 通过kubernetes.io/kube-apiserver-client-kubelet签名者获取客户端证书、通过kubernetes.io/kubelet-serving获取 TLS 服务证书；应用也可用kubernetes.io/kube-apiserver-client或自定义签名者申请证书。因此，遍历V1CertificateSigningRequestList.items时，判断csr.status.certificate是否存在即可区分"已签发"与"待审批"的请求。

而metadata的V1ListMeta则承载了集合层面的元数据，其 docstring 明确指出：ListMeta 是"合成资源（synthetic resources）"必须拥有的元数据，一个资源只能拥有 ObjectMeta 与 ListMeta 二者之一。这解释了为什么集合模型不使用V1ObjectMeta——列表本身不是一个可被 watch 到变更的独立对象。

八、文档生成机制：从 RST 到 HTML 的 automodule 链路

本仓库的doc/source/下每个模型对应一个 RST 文件，以本模型为例（doc/source/kubernetes.aio.client.models.v1_certificate_signing_request_list.rst）：

kubernetes.aio.client.models.v1\_certificate\_signing\_request\_list module =========================================================================== .. automodule:: kubernetes.aio.client.models.v1_certificate_signing_request_list :members: :show-inheritance: :undoc-members:

Sphinx 的automodule指令会在构建时读取模块，自动提取：

• 类 docstring（"CertificateSigningRequestList is a collection of CertificateSigningRequest objects"）；
• 每个公开成员（to_dict、from_dict、to_json、from_json等）的签名与文档；
• 继承关系（V1CertificateSigningRequestList(BaseModel)）；
• 未被显式文档化的成员（undoc-members）。

构建产物即为 doc/html/kubernetes.aio.client.models.v1_certificate_signing_request_list.html，与仓库中的 kubernetes/aio/docs/V1CertificateSigningRequestList.md（属性表格 + 序列化示例）互为印证。理解这条链路的意义在于：当你修改或扩展模型时，重新构建文档（见 doc/README.md 与 doc/Makefile）即可自动同步 API 参考，无需手工维护两套文档。

九、小结：何时使用 V1CertificateSigningRequestList

• 需要列出/分页遍历集群中的全部 CSR，判断待审批证书请求时，使用CertificatesV1Api.list_certificate_signing_request，返回值即本模型；
• 需要序列化一个 CSR 集合（例如备份、迁移、审计导出）时，使用to_json()/to_dict(serialize=True)；
• 需要从外部 JSON 构造集合（例如读取导出的 YAML/JSON）时，使用from_json()/from_dict()；
• 需要监听证书请求状态流转时，配合 watch 流使用，其items[].status与metadata.resource_version是关键状态来源。

相关延伸阅读路径：同步模型实现 kubernetes/client/models/v1_certificate_signing_request_list.py、异步 API 定义 kubernetes/aio/client/api/certificates_v1_api.py、列表元数据模型 kubernetes/aio/client/models/v1_list_meta.py，以及异步客户端整体使用说明 kubernetes/aio/README.md。

• 后端
• 云原生
• 容器编排