Kubernetes Python 客户端之 V1ControllerRevisionList 模型:字段、序列化与列表查询实战指南

原创2026-10-09 09:14:271,876 阅读
文章标签:云原生后端

Kubernetes Python 客户端之 V1ControllerRevisionList 模型:字段、序列化与列表查询实战指南

本篇技术指南以 Kubernetes Python 官方客户端仓库中的 kubernetes.aio.client.models.v1_controller_revision_list 模块为对象,系统讲解 V1ControllerRevisionList 模型的字段定义、与 V1ControllerRevision / V1ListMeta 的关联关系、JSON/字典序列化方法,以及如何借助 AppsV1Api 的分页列表接口获取 ControllerRevision 集合。读完本文,你将掌握在同步(kubernetes.client)与异步(kubernetes.aio.client)两种 API 风格下构造、解析和遍历 ControllerRevision 列表的完整能力。

一、模块定位与文档来源

V1ControllerRevisionList 是 Kubernetes 对象模型中"列表型资源(list kind)"的标准载体,对应 API 组 apps/v1 下的 ControllerRevision 资源。在 Kubernetes 集群中,ControllerRevision 主要用于记录控制器(如 DaemonSet、StatefulSet)在更新与回滚过程中的不可变状态快照,而 V1ControllerRevisionList 则是这些快照对象的集合容器。

本模块的官方 API 文档由 Sphinx 的 automodule 指令生成,指令所在文件为 doc/source/kubernetes.aio.client.models.v1_controller_revision_list.rst:

.. automodule:: kubernetes.aio.client.models.v1_controller_revision_list
   :members:
   :show-inheritance:
   :undoc-members:

该指令声明了 :members:(列出所有公共成员)、:show-inheritance:(显示继承关系)与 :undoc-members:(包含未编写 docstring 的成员),因此 Sphinx 生成的 HTML 文档会完整呈现模型类的全部字段与方法签名。模块的实际实现位于 kubernetes/aio/client/models/v1_controller_revision_list.py,它与其他全部模型一样,由 OpenAPI Generator 基于 Kubernetes 官方 OpenAPI 规范(本仓库对应 release-1.37)自动生成,属于 kubernetes.aio.client.models 包的一部分。

二、模型字段详解

V1ControllerRevisionList 继承自 pydantic.BaseModel,共声明 4 个字段。其英文语义为 "ControllerRevisionList is a resource containing a list of ControllerRevision objects"。

字段名(Python) 序列化字段名(wire 格式) 类型 必填 说明
api_version apiVersion str(可选) 否 对象的版本化 schema 标识;服务端会将已识别的 schema 转换到最新内部值,并可能拒绝无法识别的值
items items List[V1ControllerRevision] 是 ControllerRevision 对象列表,即本列表资源的实体数据
kind kind str(可选) 否 该 REST 资源所代表的对象类型字符串,采用 CamelCase,不可更新;服务端可从客户端请求的端点推断该值
metadata metadata V1ListMeta(可选) 否 列表级元数据(分页续传令牌、剩余数量、资源版本等)

从源码的 openapi_types 与 attribute_map 可以看出字段到 JSON 键的映射关系(v1_controller_revision_list.py):

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

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

其中 api_version 字段还通过 AliasChoices("apiVersion", "api_version") 同时接受驼峰与下划线两种输入形式,serialization_alias="apiVersion" 则保证输出时统一采用 wire 格式的驼峰命名。

2.1 核心字段 items 与元素类型 V1ControllerRevision

items 是唯一必填字段,元素类型为 kubernetes/aio/client/models/v1_controller_revision.py 中的 V1ControllerRevision。该元素模型描述 "an immutable snapshot of state data",包含以下关键字段:

  • api_version:str,可选;
  • data:Dict[str, Any],必填,状态的序列化表示;
  • kind:str,可选;
  • metadata:V1ObjectMeta,可选;
  • revision:int(StrictInt),可选,表示 data 所代表状态的修订号。

值得注意的语义约束:ControllerRevision 一旦创建成功即不可更新,API Server 会拒绝所有尝试修改 Data 字段的请求;ControllerRevision 可以被删除。由于它同时被 DaemonSet 与 StatefulSet 控制器用于更新与回滚,该对象仍处于 beta 阶段,客户端不应依赖其长期稳定性,它主要是供控制器内部使用。

2.2 列表元数据 V1ListMeta

metadata 字段的类型为 kubernetes/aio/client/models/v1_list_meta.py 中的 V1ListMeta,它承载列表资源的通用元数据,主要字段包括:

  • continue(Python 属性为 var_continue):分页续传令牌;当请求设置了 limit 且服务端还有更多数据时返回,客户端应将其原样用于下一次请求;
  • remaining_item_count(wire 名 remainingItemCount):本次列表响应未包含的后续条目数量,用于估算集合规模,客户端不应依赖其精确性;
  • resource_version(wire 名 resourceVersion):标识服务端内部对象版本的不透明字符串,客户端必须原样回传,由系统填充且只读;
  • self_link:已弃用的只读字段,系统不再填充;
  • shard_info:V1ShardInfo,与分片列表相关的可选信息。

三、序列化与反序列化方法

V1ControllerRevisionList 提供了一套完整的 JSON/字典转换方法,这也是 Sphinx 文档 :members: 指令渲染的核心成员。

3.1 从 JSON 字符串创建实例

from kubernetes.aio.client.models.v1_controller_revision_list import V1ControllerRevisionList

json_str = """
{
  "apiVersion": "apps/v1",
  "kind": "ControllerRevisionList",
  "items": [
    {
      "apiVersion": "apps/v1",
      "kind": "ControllerRevision",
      "metadata": {"name": "mystatefulset-abc123", "namespace": "default"},
      "revision": 1,
      "data": {"spec": {"replicas": 3}}
    }
  ],
  "metadata": {
    "resourceVersion": "12345",
    "continue": ""
  }
}
"""

instance = V1ControllerRevisionList.from_json(json_str)
print(instance.items[0].revision)  # 1

from_json 内部通过 json.loads 解析字符串后委托给 from_dict。from_dict 的处理逻辑(v1_controller_revision_list.py)会先执行 __preprocess_input_names 归一化键名(将 apiVersion 与 api_version 统一为 apiVersion),再对 items 逐个调用 V1ControllerRevision.from_dict,对 metadata 调用 V1ListMeta.from_dict,最后通过 pydantic 的 model_validate 完成实例化与字段校验。

3.2 序列化输出

  • to_json():返回使用 wire 别名(apiVersion、items、kind、metadata)的 JSON 字符串;
  • to_dict(serialize=False):返回 Python 字典;当 serialize=True 时键名采用 wire 格式,否则采用 Python 属性名;
  • to_str() / __repr__:返回便于 print 的可读字符串表示(基于 pprint.pformat);
  • __eq__ / __ne__:基于 to_dict() 的字典等价性比较两个列表实例。
d = instance.to_dict(serialize=True)
print(d["apiVersion"])            # apps/v1
print(instance.to_json())

3.3 pydantic 配置行为

模型类通过 model_config = ConfigDict(validate_by_name=True, validate_by_alias=True, validate_assignment=True, extra="forbid", protected_namespaces=()) 开启严格校验:既允许按字段名也允许按别名传入;字段赋值时即时校验;未知字段直接报错(extra="forbid"),这保证了与 Kubernetes API 严格对齐。

四、通过 AppsV1Api 获取 ControllerRevision 列表

V1ControllerRevisionList 最常见的来源是 AppsV1Api 的列表接口。在异步实现 kubernetes/aio/client/api/apps_v1_api.py 中,有两个方法返回 V1ControllerRevisionList:

  • list_namespaced_controller_revision(第 8197 行起):列出指定命名空间下的 ControllerRevision;
  • list_controller_revision_for_all_namespaces(第 6817 行起):跨所有命名空间列出。

以 list_controller_revision_for_all_namespaces 为例,其 200 响应类型映射为 V1ControllerRevisionList(源码中 _response_types_map = {'200': "V1ControllerRevisionList", '401': None}),异步调用链路为 await 序列化参数 → call_api → await response_data.read() → response_deserialize。

4.1 异步列表查询示例

import asyncio
from kubernetes import config
from kubernetes.aio import client as aio_client

async def list_all_controller_revisions():
    await config.load_kube_config()
    async with aio_client.ApiClient() as api_client:
        api = aio_client.AppsV1Api(api_client)
        resp = await api.list_controller_revision_for_all_namespaces(
            label_selector="app=myapp",
            limit=100,
        )
        # resp 为 V1ControllerRevisionList
        print("kind:", resp.kind)
        print("resourceVersion:", resp.metadata.resource_version if resp.metadata else None)
        for rev in resp.items:
            print(rev.metadata.name, "revision:", rev.revision)

asyncio.run(list_all_controller_revisions())

该接口支持丰富的查询参数:label_selector / field_selector 过滤、limit 限制单页条数、resource_version 与 resource_version_match 控制一致性读取、timeout_seconds 限制调用时长、watch=True 切换为流式监听、send_initial_events 用于 watch 时先发送初始状态合成事件等。当 limit 导致结果被截断时,服务端会在列表的 metadata.continue 字段返回续传令牌,客户端可将其作为 _continue 参数发起下一页请求(令牌有效期一般 5 到 15 分钟,过期或配置变化时服务端会返回 410 ResourceExpired)。

4.2 同步版本与分页遍历

同步客户端同样提供完全一致的模型与接口:模型定义位于 kubernetes/client/models/v1_controller_revision_list.py,API 文档见 kubernetes/docs/V1ControllerRevisionList.md 与异步版 kubernetes/aio/docs/V1ControllerRevisionList.md。两个包均通过 kubernetes/client/__init__.py 与 kubernetes/aio/client/__init__.py 导出 V1ControllerRevisionList,可直接 from kubernetes.client import V1ControllerRevisionList 导入。

from kubernetes import client, config

config.load_kube_config()
api = client.AppsV1Api()
resp = api.list_namespaced_controller_revision("default", limit=50)

while True:
    for rev in resp.items:
        print(rev.metadata.name, rev.revision)
    if not resp.metadata or not resp.metadata._continue:
        break
    resp = api.list_namespaced_controller_revision(
        "default", limit=50, _continue=resp.metadata._continue
    )

五、使用注意事项与最佳实践

  1. items 为必填字段:构造 V1ControllerRevisionList 时至少需要提供空列表 [],否则 pydantic 校验会报错;api_version、kind、metadata 均可省略。
  2. apiVersion / kind 双输入:由于 AliasChoices 支持 apiVersion 与 api_version 两种键名,解析来自 kubectl get -o json 的输出时可以放心使用原始 wire 格式。
  3. 分页与一致性:大集合应使用 limit + _continue 分页;对强一致列表有要求的场景建议设置 resource_version_match,并在收到 410 时从头重新发起请求。
  4. ControllerRevision 的不可变性:列表中的元素对象创建后不可修改 Data 字段,客户端如需"更新"应通过新建 Revision 而非原地修改。
  5. 同步/异步 API 对称性:kubernetes.aio.client 与 kubernetes.client 的模型类在字段与方法上完全对称,仅异步 API 方法为 async def,方便在同一项目中混用两种风格。

六、参考资源

登录后查看全文
python