Kubernetes Python 客户端之 V1ControllerRevisionList 模型:字段、序列化与列表查询实战指南
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
)
五、使用注意事项与最佳实践
items为必填字段:构造V1ControllerRevisionList时至少需要提供空列表[],否则 pydantic 校验会报错;api_version、kind、metadata均可省略。apiVersion/kind双输入:由于AliasChoices支持apiVersion与api_version两种键名,解析来自kubectl get -o json的输出时可以放心使用原始 wire 格式。- 分页与一致性:大集合应使用
limit+_continue分页;对强一致列表有要求的场景建议设置resource_version_match,并在收到 410 时从头重新发起请求。 - ControllerRevision 的不可变性:列表中的元素对象创建后不可修改
Data字段,客户端如需"更新"应通过新建 Revision 而非原地修改。 - 同步/异步 API 对称性:
kubernetes.aio.client与kubernetes.client的模型类在字段与方法上完全对称,仅异步 API 方法为async def,方便在同一项目中混用两种风格。
六、参考资源
- RST 文档源:doc/source/kubernetes.aio.client.models.v1_controller_revision_list.rst
- 异步模型实现:kubernetes/aio/client/models/v1_controller_revision_list.py
- 元素模型实现:kubernetes/aio/client/models/v1_controller_revision.py
- 列表元数据实现:kubernetes/aio/client/models/v1_list_meta.py
- 列表接口文档:kubernetes/aio/docs/AppsV1Api.md、kubernetes/docs/AppsV1Api.md
- 同步模型文档:kubernetes/docs/V1ControllerRevisionList.md
- 异步模型文档:kubernetes/aio/docs/V1ControllerRevisionList.md