深入解析 Kubernetes Python 客户端 V1ServiceAccount 模型:字段、序列化与实战操作
深入解析 Kubernetes Python 客户端 V1ServiceAccount 模型:字段、序列化与实战操作
本文以 Kubernetes 官方 Python 客户端(kubernetes)异步版 kubernetes.aio.client.models.v1_service_account 模块中的 V1ServiceAccount 模型为核心,围绕其字段语义、Pydantic 序列化机制与 CoreV1Api 中的 ServiceAccount 操作 API,讲解如何在集群内外用 Python 创建、读取、更新和删除 ServiceAccount,并给出可直接运行的同步/异步示例。读完本文,你将掌握该模型全部字段的用途、别名(alias)序列化规则、与 V1ObjectMeta、V1ObjectReference、V1LocalObjectReference 等关联模型的组合方式,以及通过 TokenRequest 获取令牌的正确姿势。
V1ServiceAccount 模型是什么
V1ServiceAccount 是 Kubernetes core/v1 API 中 ServiceAccount 资源在 Python 客户端里的类型化表示。它的类文档用一句话概括了该资源的本质(见 v1_service_account.py):
ServiceAccount binds together: a name(一个用户可理解、周边系统可识别的名称), a principal(可被认证与授权的身份主体), a set of secrets(一组 Secret)。
也就是说,ServiceAccount 把「名称」「身份主体」「一组 Secret」三者绑定在一起,是 Pod 访问 Kubernetes API Server 的默认身份凭证来源。仓库中存在两套并行实现:
- 同步版:kubernetes/client/models/v1_service_account.py
- 异步版(本文主体):kubernetes/aio/client/models/v1_service_account.py
两者均基于 OpenAPI Generator 从 release-1.37 版本的 OpenAPI 规范自动生成(见 kubernetes/aio/README.md 中的 "API version: release-1.37"),类名为 V1ServiceAccount,继承自 pydantic.BaseModel。
模型字段全景:六个属性逐一拆解
根据 v1_service_account.py 中的字段声明,模型共有 6 个可选字段,同时类变量 openapi_types 给出了每个字段的 Python 类型映射:
| 字段(Python 属性名) | 类型(openapi_types) | 线上 JSON 键(attribute_map) | 说明 |
|---|---|---|---|
api_version |
str |
apiVersion |
对象的 API 版本 schema 标识 |
automount_service_account_token |
bool |
automountServiceAccountToken |
是否自动向使用该 SA 的 Pod 挂载 API Token |
image_pull_secrets |
List[V1LocalObjectReference] |
imagePullSecrets |
拉取镜像所需 Secret 的引用列表 |
kind |
str |
kind |
REST 资源类型,固定为 ServiceAccount |
metadata |
V1ObjectMeta |
metadata |
对象元数据 |
secrets |
List[V1ObjectReference] |
secrets |
允许 Pod 使用的同命名空间 Secret 列表 |
api_version 与 kind:资源定位标识
api_version(线上键apiVersion)用于定义该对象表示形式的版本化 schema,服务器会把可识别的 schema 转换到最新的内部值。客户端代码中对此字段的说明来自 v1_service_account.py 的字段描述,即v1(core 组的 v1 版本)。kind为ServiceAccount,遵循 Kubernetes API 约定(CamelCase),且创建后不可更新。
metadata:V1ObjectMeta 元数据
metadata 的类型是 V1ObjectMeta,它是所有持久化资源都必须携带的元数据结构,关键子字段包括:
name:命名空间内唯一,创建资源时必须指定;namespace:空值等价于default命名空间;labels/annotations:标签与注解的字符串键值映射;generate_name:未提供name时由服务器生成唯一名称的前缀;uid、resource_version、creation_timestamp等由系统填充、只读的字段。
automount_service_account_token:Token 自动挂载开关
该布尔字段指示「以该 ServiceAccount 运行的 Pod 是否应自动挂载 API Token」,并可在 Pod 级别覆盖。它是实践中最常被调整的字段之一:对于不需要访问 API Server 的工作负载,通常将其设为 False 以减小凭证暴露面。
image_pull_secrets:镜像拉取凭证
image_pull_secrets 是一个 V1LocalObjectReference 列表。V1LocalObjectReference(见 v1_local_object_reference.py)只包含一个 name 字段,用于引用同一命名空间内的 Secret。字段描述特别强调:ImagePullSecrets 与普通 Secret 不同——Secret 可以挂载进 Pod,而 ImagePullSecrets 仅由 kubelet 访问,用于拉取引用了该 ServiceAccount 的 Pod 中的镜像。
secrets:可挂载 Secret 白名单
secrets 是 V1ObjectReference 列表,V1ObjectReference(见 v1_object_reference.py)包含 name、namespace、kind、api_version、uid、resource_version、field_path 等引用定位字段。字段说明包含几个重要约束(来自 v1_service_account.py):
- 只有当 ServiceAccount 带有
kubernetes.io/enforce-mountable-secrets注解(值设为true)时,Pod 才被限制只能挂载该列表内的 Secret; - 该注解自 Kubernetes v1.32 起已被弃用,官方建议改用独立命名空间来隔离可挂载 Secret 的访问;
- 不要用该字段去查找自动生成的 ServiceAccount Token Secret 供 Pod 外部使用——正确的做法是通过 TokenRequest API 直接请求令牌,或手动创建 ServiceAccount Token Secret。
序列化机制:alias 双向转换与 to_dict/from_dict
模型从 OpenAPI Generator 生成,同时支持「Python 风格下划线命名」与「Kubernetes 线上 camelCase 命名」两套字段名。
字段名预处理与 Alias 配置
在 v1_service_account.py 中,每个字段都通过 AliasChoices 同时接受 camelCase 与 snake_case 两种输入,并通过 serialization_alias 指定序列化时的线上键。__preprocess_input_names 类方法(L134-L152)会把 snake_case 键归一化为 camelCase 键,例如:
api_version→apiVersionautomount_service_account_token→automountServiceAccountTokenimage_pull_secrets→imagePullSecrets
而 model_config 采用了 validate_by_name=True、validate_by_alias=True、validate_assignment=True、extra="forbid" 的严格配置(L154-L160),意味着未知字段会被拒绝,赋值时会触发校验。
实例化与反序列化示例
from_dict 会先做字段名预处理,再递归调用关联模型的 from_dict 构造嵌套对象;from_json 则先解析 JSON 字符串再走 from_dict。官方配套文档 V1ServiceAccount.md 给出了完整示例:
from kubernetes.aio.client.models.v1_service_account import V1ServiceAccount
# 从 JSON 字符串创建实例
json = "{}"
v1_service_account_instance = V1ServiceAccount.from_json(json)
# 输出对象的 JSON 字符串表示
print(V1ServiceAccount.to_json())
# 转换为 dict
v1_service_account_dict = v1_service_account_instance.to_dict()
# 从 dict 重新创建实例
v1_service_account_from_dict = V1ServiceAccount.from_dict(v1_service_account_dict)
其中 to_dict(serialize=False) 默认输出下划线键名的公开字段字典,serialize=True 时输出 camelCase 线上键;to_json() 则始终基于 alias 输出线上 JSON。类中的 __openapi_generator_modern_projection(L209-L242)对 metadata、image_pull_secrets、secrets 中的嵌套模型逐一调用 to_dict(),保证嵌套结构也能正确展开。
关联模型:V1ServiceAccountList 与 TokenRequest
列表容器 V1ServiceAccountList
当调用 list_namespaced_service_account 查询多个对象时,返回类型是 V1ServiceAccountList,它包含 items(必填,List[V1ServiceAccount])、metadata(V1ListMeta)与 api_version、kind。
Token 获取:create_namespaced_service_account_token
在 core_v1_api.py 中提供了异步方法 create_namespaced_service_account_token(name, namespace, body),body 为 AuthenticationV1TokenRequest。这是替代「读取 secrets 字段获取 Token」的官方推荐途径。
实战:用 CoreV1Api 操作 ServiceAccount
V1ServiceAccount 对象本身只是数据模型,真正的 CRUD 操作由 CoreV1Api 提供。同步版 API 位于 kubernetes/client/api/core_v1_api.py,异步版位于 kubernetes/aio/client/api/core_v1_api.py,两者的核心方法签名一一对应:
| 操作 | 方法(异步版) | 关键参数 |
|---|---|---|
| 创建 | create_namespaced_service_account |
namespace、body: V1ServiceAccount,可选 pretty、dry_run、field_manager |
| 读取 | read_namespaced_service_account |
name、namespace |
| 列表 | list_namespaced_service_account |
namespace,可选 field_selector、label_selector、limit、_continue 等 |
| 替换 | replace_namespaced_service_account |
name、namespace、body |
| 局部更新 | patch_namespaced_service_account |
name、namespace、body |
| 删除 | delete_namespaced_service_account |
name、namespace,可选 grace_period_seconds |
同步示例:创建并读取 ServiceAccount
from kubernetes import client, config
config.load_kube_config()
v1 = client.CoreV1Api()
sa = client.V1ServiceAccount(
metadata=client.V1ObjectMeta(name="my-sa", namespace="default"),
automount_service_account_token=False,
)
# 创建
created = v1.create_namespaced_service_account(namespace="default", body=sa)
print(created.metadata.name, created.metadata.uid)
# 读取
got = v1.read_namespaced_service_account(name="my-sa", namespace="default")
print(got.to_dict())
# 更新 imagePullSecrets
got.image_pull_secrets = [client.V1LocalObjectReference(name="registry-key")]
v1.replace_namespaced_service_account(name="my-sa", namespace="default", body=got)
异步示例:基于 asyncio 的操作
异步客户端的使用模式参考 examples_asyncio/list_pods.py:先 await config.load_kube_config(),再用 ApiClient 上下文管理器创建 CoreV1Api 实例。
import asyncio
from kubernetes.aio import client, config
from kubernetes.aio.client.api_client import ApiClient
async def main():
await config.load_kube_config()
async with ApiClient() as api:
v1 = client.CoreV1Api(api)
sa = client.V1ServiceAccount(
metadata=client.V1ObjectMeta(name="my-sa", namespace="default"),
automount_service_account_token=False,
)
created = await v1.create_namespaced_service_account(namespace="default", body=sa)
print(created.metadata.name)
# 遍历命名空间内所有 ServiceAccount
listed = await v1.list_namespaced_service_account(namespace="default")
for item in listed.items:
print(item.metadata.name)
if __name__ == "__main__":
asyncio.run(main())
通过 TokenRequest 获取访问令牌
from kubernetes import client, config
from kubernetes.client.models.authentication_v1_token_request import AuthenticationV1TokenRequest
from kubernetes.client.models.v1_token_request_spec import V1TokenRequestSpec
config.load_kube_config()
v1 = client.CoreV1Api()
req = AuthenticationV1TokenRequest(
spec=V1TokenRequestSpec(audiences=["https://kubernetes.default.svc"]),
)
resp = v1.create_namespaced_service_account_token(
name="my-sa", namespace="default", body=req
)
print(resp.status.token)
与文档体系的对应关系
- 模型属性表与官方示例见 kubernetes/docs/V1ServiceAccount.md(同步版)与 kubernetes/aio/docs/V1ServiceAccount.md(异步版),本文字段说明与之一致;
- 所有 ServiceAccount 相关 API 的完整参数列表见 kubernetes/docs/CoreV1Api.md 与 kubernetes/aio/docs/CoreV1Api.md;
- 若需在集群内部署时自动获得 ServiceAccount 身份,可参考 examples/in_cluster_config.py 中基于挂载的 ServiceAccount Token 加载集群配置的方式。
小结
V1ServiceAccount 是 Kubernetes Python 客户端中模型层的一个典型代表:它用 6 个可选字段完整承载 ServiceAccount 的身份、凭证与元数据语义,通过 Pydantic 的 alias 机制在 snake_case 与 camelCase 之间无缝切换,并通过 from_json / from_dict / to_dict / to_json 四个方法完成与 JSON / dict 的双向转换。掌握该模型后,你可以用同步或异步的 CoreV1Api 完整管理 ServiceAccount 生命周期,并遵循 v1.32 之后的安全建议,用 TokenRequest 而非读取 secrets 字段来获取服务账号令牌。