Kubernetes Python 客户端 V2PodsMetricStatus 模型详解:HPA Pods 类型指标的状态读取与序列化
Kubernetes Python 客户端 V2PodsMetricStatus 模型详解:HPA Pods 类型指标的状态读取与序列化
V2PodsMetricStatus 是 Kubernetes Python 官方客户端(kubernetes / kubernetes.aio)中用于描述 HPA(Horizontal Pod Autoscaler)autoscaling/v2 API 下 Pods 类型指标当前状态的模型类。本文以 Sphinx 文档入口 及其对应的 异步模型源码 为主体,详细解析该模型的两个必填字段、与其关联的 V2MetricValueStatus、V2MetricIdentifier 子模型、序列化/反序列化 API,并结合 autoscaling/v2 的 HPA 读取接口给出实战示例。读完本文,你将能准确理解并安全地在同步与异步客户端中构造、解析和校验 Pods 类型指标状态数据。
一、文档定位:这是一个 automodule 驱动的 API 模型文档
该 RST 文件是项目使用 Sphinx automodule 指令为 kubernetes.aio.client.models.v2_pods_metric_status 模块自动生成的文档入口:
.. automodule:: kubernetes.aio.client.models.v2_pods_metric_status
:members:
:show-inheritance:
:undoc-members:
它本身并不承载叙述性内容,而是声明"把该模块下所有成员(含继承关系与未文档化成员)渲染进 API 文档"。也就是说,真正的技术主体是模块中由 OpenAPI Generator 依据 Kubernetes OpenAPI 规范(本文档对应 release-1.37,见 模型源码 文件头)生成的 V2PodsMetricStatus 模型类。项目同时在 同步客户端文档 与 异步客户端文档 中提供了该模型的属性说明与代码示例。
二、模型语义:Pods 指标状态在 HPA 中的角色
V2PodsMetricStatus 表示"当前缩放目标(scale target)中描述每个 Pod 的某个指标(例如 transactions-processed-per-second)的当前值"。在 autoscaling/v2 的 HPA 状态模型中,它作为 V2MetricStatus 的 pods 字段存在(见 V2MetricStatus 源码 第 114 行),而 V2MetricStatus 又作为 V2HorizontalPodAutoscalerStatus.current_metrics 列表的元素出现(见 V2HorizontalPodAutoscalerStatus 源码 第 110 行)。
从 OpenAPI 规范(swagger.json 中 v2.PodsMetricStatus 定义,第 4541 行起)可以确认:
metric与current均为 required(必填) 字段;metric用于"按名称和选择器标识目标指标";current用于"保存给定指标的当前值"。
与"源(Source)"侧模型 V2PodsMetricSource(同步版源码)对应,Pods 类型指标的核心特点是:每个 Pod 单独上报指标值,所有值会被平均后再与目标值比较——这正是它与 Resource 类型指标(在 Pod 内嵌资源指标上缩放)的关键区别。这一语义直接决定了下文 current 字段中 averageValue/averageUtilization 的含义。
三、字段详解:两个必填属性与三种取值口径
V2PodsMetricStatus 类体十分精简(异步源码 第 97–126 行):
class V2PodsMetricStatus(BaseModel):
current: V2MetricValueStatus
metric: V2MetricIdentifier
openapi_types: ClassVar[Dict[str, str]] = {
"current": "V2MetricValueStatus",
"metric": "V2MetricIdentifier"
}
attribute_map: ClassVar[Dict[str, str]] = {
"current": "current",
"metric": "metric"
}
__properties: ClassVar[List[str]] = ["current", "metric"]
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
current |
V2MetricValueStatus |
是 | 给定指标在当前缩放目标下的当前值 |
metric |
V2MetricIdentifier |
是 | 按名称(name)与可选选择器(selector)标识目标指标 |
3.1 metric:指标标识
V2MetricIdentifier(异步源码)只有两个字段:
name(str,必填):指标名称,例如transactions-processed-per-second;selector(V1LabelSelector,可选):用于从指标服务中过滤特定 Pod 集合的标签选择器。
V1LabelSelector 支持 matchLabels(Dict<a href="https://link.gitcode.com/i/6652e23cc2eb11ec4ee6ee33f495a7dc" target="_blank">str, str])与 matchExpressions(List[V1LabelSelectorRequirement])两类条件,且所有条件之间是 AND 语义;空选择器匹配所有对象,null 选择器不匹配任何对象(见 [V1LabelSelector 文档)。
3.2 current:当前值的三种口径
V2MetricValueStatus(异步源码)定义了"当前值"的三种表达方式,三者均为可选(Optional),实际由 HPA 控制面按指标类型填充:
| 字段 | 类型 | 含义 |
|---|---|---|
average_utilization |
int(可选) |
资源指标在所有相关 Pod 上的平均值,以 Pod 资源请求值的百分比表示 |
average_value |
str(可选) |
指标在所有相关 Pod 上的平均值,以 quantity(数量字符串,如 "1k"、"500m")表示 |
value |
str(可选) |
指标的当前值,以 quantity 表示 |
在 Pods 类型指标下,因为"各 Pod 取值后取平均"是固定语义,current 中最常见的是 averageValue(对应源侧 target.type: AverageValue)。averageUtilization 在 OpenAPI 规范中标注为"当前仅对 Resource 指标源有效",因此出现在 Pods 状态中时需结合实际情况判断。
四、序列化与反序列化:完整方法清单与调用示例
模型继承了 pydantic v2 的 BaseModel,并基于 ConfigDict 设置了严格校验策略(异步源码 第 120–126 行):
model_config = ConfigDict(
validate_by_name=True,
validate_by_alias=True,
validate_assignment=True,
extra="forbid",
protected_namespaces=(),
)
这意味着:传入未知字段会直接报错(extra="forbid");赋值时立即校验类型(validate_assignment=True);字段名与 JSON 别名(camelCase)同时接受(validate_by_name + validate_by_alias)。
类提供的公开方法(同步版 kubernetes/client/models/v2_pods_metric_status.py 与异步版完全同构):
| 方法 | 作用 |
|---|---|
to_json() |
按别名返回 JSON 字符串表示(camelCase 字段名) |
from_json(json_str) |
从 JSON 字符串创建实例(内部走 from_dict) |
to_dict(serialize=False) |
返回所有声明的模型字段字典;serialize=True 时输出线格式(wire)名称 |
from_dict(obj) |
从 dict 创建实例,并递归调用子模型 V2MetricValueStatus.from_dict、V2MetricIdentifier.from_dict |
to_str() / __repr__() |
返回 pprint 格式化的可读字符串 |
__eq__ / __ne__ |
基于 to_dict() 结果做值比较 |
官方文档给出的完整示例(摘自 同步文档):
from kubernetes.client.models.v2_pods_metric_status import V2PodsMetricStatus
json = "{}"
# create an instance of V2PodsMetricStatus from a JSON string
v2_pods_metric_status_instance = V2PodsMetricStatus.from_json(json)
# print the JSON string representation of the object
print(V2PodsMetricStatus.to_json())
# convert the object into a dict
v2_pods_metric_status_dict = v2_pods_metric_status_instance.to_dict()
# create an instance of V2PodsMetricStatus from a dict
v2_pods_metric_status_from_dict = V2PodsMetricStatus.from_dict(v2_pods_metric_status_dict)
异步客户端(kubernetes.aio)的导入路径为 kubernetes.aio.client.models.v2_pods_metric_status,其余用法一致(见 异步文档)。
4.1 构造一个真实的 Pods 指标状态
以"每秒处理事务数"指标为例,一个典型的构造与往返序列化过程如下:
from kubernetes.aio.client.models.v2_metric_identifier import V2MetricIdentifier
from kubernetes.aio.client.models.v2_metric_value_status import V2MetricValueStatus
from kubernetes.aio.client.models.v2_pods_metric_status import V2PodsMetricStatus
status = V2PodsMetricStatus(
metric=V2MetricIdentifier(name="transactions-processed-per-second"),
current=V2MetricValueStatus(average_value="1.2k"),
)
# 序列化为 JSON(wire 格式,camelCase)
print(status.to_json())
# {"metric": {"name": "transactions-processed-per-second"}, "current": {"averageValue": "1.2k"}}
# 反序列化往返
restored = V2PodsMetricStatus.from_json(status.to_json())
assert restored == status
从源码层面看,from_dict 对子字段的递归解析逻辑为(异步源码 第 209–222 行):
_obj = cls.model_validate({
"current": V2MetricValueStatus.from_dict(obj["current"]) if obj.get("current") is not None else None,
"metric": V2MetricIdentifier.from_dict(obj["metric"]) if obj.get("metric") is not None else None
})
而 to_dict 则通过 _to_legacy_value 将子模型递归转换为字典;若子模型实现了 OpenAPI Generator 的现代投影(_openapi_generator_to_dict),则会调用带 serialize 参数的版本以正确输出线格式字段名。
五、实战:从 HPA 状态中读取 Pods 指标
在真实场景中,V2PodsMetricStatus 通常不是单独构造的,而是随 HPA 状态一起由 API 服务器返回。官方客户端提供了完整的 autoscaling/v2 接口(同步版 API、异步版 API),其中 read_namespaced_horizontal_pod_autoscaler(name, namespace) 返回 V2HorizontalPodAutoscaler(同步版源码 第 2749 行起)。
5.1 同步客户端读取示例
from kubernetes import client, config
config.load_kube_config()
v2 = client.AutoscalingV2Api()
hpa = v2.read_namespaced_horizontal_pod_autoscaler(
name="my-hpa",
namespace="default",
)
for metric_status in hpa.status.current_metrics: # List[V2MetricStatus]
if metric_status.type == "Pods" and metric_status.pods:
pods = metric_status.pods
print("metric:", pods.metric.name)
print("average value:", pods.current.average_value)
if pods.metric.selector:
print("selector:", pods.metric.selector.match_labels)
5.2 异步客户端读取示例
kubernetes.aio 提供完全对应的异步 API,适合在事件循环中并发读取多个 HPA:
import asyncio
from kubernetes import config
from kubernetes.aio import client as aio_client
async def main():
await config.load_kube_config() # aio 客户端支持异步加载配置
v2 = aio_client.AutoscalingV2Api()
hpa = await v2.read_namespaced_horizontal_pod_autoscaler(
name="my-hpa",
namespace="default",
)
for metric_status in (hpa.status.current_metrics or []):
if metric_status.type == "Pods" and metric_status.pods:
print(metric_status.pods.to_dict())
asyncio.run(main())
5.3 对应的 HPA 配置形态
一个使用 Pods 指标源(对应状态侧即为 V2PodsMetricStatus)的 HPA 典型 YAML 如下:
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: my-hpa
namespace: default
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: my-app
minReplicas: 1
maxReplicas: 10
metrics:
- type: Pods
pods:
metric:
name: transactions-processed-per-second
target:
type: AverageValue
averageValue: "1k"
部署后,kubectl get hpa my-hpa -o json 的 status.currentMetrics 数组中出现 type: "Pods" 的条目时,其 pods 对象即为本文所述的 V2PodsMetricStatus。
六、底层实现要点:OpenAPI 生成代码的结构
从 同步版模型源码 可以看到生成代码的共性骨架:
- 头部工具函数:
_get_openapi_to_dict、_to_legacy_item、_to_legacy_value、_to_openapi_value等,用于在 pydantic 原生model_dump与 OpenAPI 线格式之间互转,保持与旧版python-legacy生成器行为兼容(源码注释中明确引用了 legacy 模板的转换逻辑)。 - 元数据类变量:
openapi_types(属性名→OpenAPI 类型字符串映射)与attribute_map(属性名→JSON key 映射),二者在反序列化与文档渲染中承担类型/别名查找职责。 __openapi_generator_modern_projection:通过model_dump(by_alias=True, exclude_none=True)生成字典,再用_to_openapi_value递归展开子模型;该函数与to_dict通过setattr互相挂载,形成"现代投影"机制。- 校验策略:
extra="forbid"保证客户端能及时暴露 API 返回了未知字段的情况,protected_namespaces=()避免 pydantic 对以model_等前缀开头的字段名的保留限制。
这些实现细节对所有 kubernetes.client.models 下的模型(约 900 余个)是一致的,理解 V2PodsMetricStatus 即可举一反三。
七、同步版与异步版的差异
kubernetes.aio.client.models.v2_pods_metric_status.V2PodsMetricStatus 与 kubernetes.client.models.v2_pods_metric_status.V2PodsMetricStatus 在类定义、字段、校验与序列化行为上完全一致(两份源码逐行同构,仅在导入路径上引用各自的子模型模块)。二者的真正差异体现在 API 层:kubernetes.aio 下的 AutoscalingV2Api 方法返回 awaitable,适用于 asyncio 编程模型。因此,模型对象可以在两种客户端之间按需复用,仅需注意对应的导入路径:
# 同步
from kubernetes.client.models.v2_pods_metric_status import V2PodsMetricStatus
# 异步
from kubernetes.aio.client.models.v2_pods_metric_status import V2PodsMetricStatus
八、小结
V2PodsMetricStatus承载 HPAautoscaling/v2中 Pods 类型指标的状态,由必填的metric(指标标识)与current(当前值)组成。- 当前值有
averageUtilization、averageValue、value三种口径,Pods 场景下以平均值语义为主。 - 模型基于 pydantic v2,支持严格校验(
extra="forbid")、别名双向解析,以及to_json/from_json/to_dict/from_dict完整序列化循环。 - 实战中它作为
V2MetricStatus.pods字段随 HPA 状态返回,可通过read_namespaced_horizontal_pod_autoscaler在同步或异步客户端中直接读取。
相关参考文件:模型源码(异步)、模型源码(同步)、子模型 V2MetricValueStatus、子模型 V2MetricIdentifier、状态容器 V2MetricStatus、OpenAPI 规范定义。