Kubernetes Python 客户端 V2PodsMetricStatus 模型详解:HPA Pods 类型指标的状态读取与序列化

原创2026-10-11 22:14:481,714 阅读
文章标签:云原生后端

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 生成代码的结构

从 同步版模型源码 可以看到生成代码的共性骨架:

  1. 头部工具函数:_get_openapi_to_dict、_to_legacy_item、_to_legacy_value、_to_openapi_value 等,用于在 pydantic 原生 model_dump 与 OpenAPI 线格式之间互转,保持与旧版 python-legacy 生成器行为兼容(源码注释中明确引用了 legacy 模板的转换逻辑)。
  2. 元数据类变量:openapi_types(属性名→OpenAPI 类型字符串映射)与 attribute_map(属性名→JSON key 映射),二者在反序列化与文档渲染中承担类型/别名查找职责。
  3. __openapi_generator_modern_projection:通过 model_dump(by_alias=True, exclude_none=True) 生成字典,再用 _to_openapi_value 递归展开子模型;该函数与 to_dict 通过 setattr 互相挂载,形成"现代投影"机制。
  4. 校验策略: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 承载 HPA autoscaling/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 规范定义。

登录后查看全文
python