Kubernetes v1.37 将资源指标 API 正式提升为稳定版本：metrics.k8s.io/v1。这意味着节点与 Pod 的 CPU、内存使用量查询接口获得了稳定 API 的兼容性承诺。对日常使用 kubectl top、依赖资源指标的自动扩缩容，以及直接调用聚合 API 的平台团队而言，重点不在于理解一套新指标，而在于完成一次明确的 API 版本迁移。
需要特别澄清的是：这次升级没有改变指标的采集方式、字段名称或 CPU 和内存数值的语义。v1 与此前的 v1beta1 提供相同的资源类型和字段，变化仅发生在 API Group Version。
稳定的是接口契约，不是监控系统能力
资源指标 API 已经存在很长时间：它在 Kubernetes v1.6 以 alpha 形式出现，v1.8 进入 beta，并被 kubectl top、HorizontalPodAutoscaler（HPA）等客户端长期用于生产环境。v1.37 将这条被广泛验证的接口路径正式固化为 metrics.k8s.io/v1。
该 API 保持了刻意精简的设计，只暴露两种资源：
NodeMetrics：一个节点的 CPU 与内存使用情况。PodMetrics：一个 Pod 的 CPU 与内存使用情况，并通过containers字段给出容器级拆分。
它适合回答“这个 Pod 当前消耗了多少资源”“节点的即时资源使用量如何”这类问题，也能支撑基于资源利用率的自动扩缩容。它并不替代 Prometheus 一类完整监控体系，更不能代替 custom.metrics.k8s.io 提供的自定义业务指标。
例如，QPS、订单堆积量、Kafka consumer lag 等指标不属于 Resource Metrics API 的职责范围。不要因为 metrics.k8s.io/v1 稳定化，就试图把它扩展成通用可观测性查询接口。
v1 与 v1beta1：返回结构没有变化
在 v1.37 中，稳定版路径如下：
kubectl get --raw /apis/metrics.k8s.io/v1/nodes
kubectl get --raw /apis/metrics.k8s.io/v1/namespaces/default/pods
典型的 Pod 指标响应仍然会包含 Pod 范围内的汇总信息和容器明细，结构重点如下：
{
"kind": "PodMetricsList",
"apiVersion": "metrics.k8s.io/v1",
"items": [
{
"metadata": {
"name": "api-7f9b6d8f8d-x2kqj",
"namespace": "default"
},
"timestamp": "2026-01-15T10:00:00Z",
"window": "30s",
"containers": [
{
"name": "api",
"usage": {
"cpu": "42m",
"memory": "128Mi"
}
}
]
}
]
}
因此，已有客户端通常只需将请求路径中的 v1beta1 替换为 v1。如果代码已经通过 Kubernetes API discovery 发现可用版本，则应优先选择 v1，同时在过渡期保留对 v1beta1 的兼容处理。
kubectl top 已具备这类兼容能力：当集群提供 v1 时优先使用它，否则自动回退到 v1beta1。不过，Kubernetes v1.37 的 HPA 控制器仍只支持 v1beta1；基于 API discovery 在 v1 和 v1beta1 间自动选择的支持尚未在该版本提供。运营团队不能仅因 v1 API 已稳定，就提前移除 v1beta1 服务。
先确认聚合 API 与 metrics-server 的实际状态
Metrics API 通过 Kubernetes API Aggregation Layer 提供，不由 kube-apiserver 自己直接采集节点和 Pod 指标。常见实现是 metrics-server，但集群也可以采用其他兼容 metrics.k8s.io 的实现。
升级控制面到 Kubernetes v1.37 本身，并不自动保证 /apis/metrics.k8s.io/v1 可用。指标实现必须实际提供 v1 API，并且集群必须注册对应的 APIService。
可以这样检查集群当前暴露了哪些版本：
kubectl get --raw /apis/metrics.k8s.io/ | jq .
预期输出中应能看到 v1。接着检查聚合 API 服务状态：
kubectl get apiservice v1.metrics.k8s.io
重点关注 AVAILABLE 列。若其不是 True，再查看详情与关联服务：
kubectl describe apiservice v1.metrics.k8s.io
kubectl get svc,endpoints -A | grep metrics
kubectl top nodes
这里的排查方向通常包括：metrics-server 是否已升级到支持 v1 的版本、其 Service 是否有可用 Endpoints、聚合层到后端的 TLS 配置是否正常，以及 metrics-server 是否能从 kubelet 获取指标。
可以这样实践：让自动化脚本优先使用 v1 并保留回退
如果团队有脚本直接请求 Metrics API，建议不要把 API 版本硬编码为单一路径。下面的 Bash 示例会先探测 v1，不可用时再回退到 v1beta1，并拉取指定命名空间的 Pod 指标。
运行前需要本地 kubectl 已连接目标集群，并安装 jq。
#!/usr/bin/env bash
set -euo pipefail
namespace="${1:-default}"
versions_json="$(kubectl get --raw /apis/metrics.k8s.io/)"
if jq -e '.versions[] | select(.version == "v1")' >/dev/null <<<"${versions_json}"; then
api_version="v1"
elif jq -e '.versions[] | select(.version == "v1beta1")' >/dev/null <<<"${versions_json}"; then
api_version="v1beta1"
else
echo "metrics.k8s.io is not available in this cluster" >&2
exit 1
fi
kubectl get --raw "/apis/metrics.k8s.io/${api_version}/namespaces/${namespace}/pods" \
| jq -r '.items[] | .metadata.name as $pod | .containers[] | [$pod, .name, .usage.cpu, .usage.memory] | @tsv'
执行方式：
chmod +x pod-metrics.sh
./pod-metrics.sh default
输出会是制表符分隔的 Pod 名、容器名、CPU 使用量和内存使用量，适合继续交给 awk、sort 或 CI 检查脚本处理。
如果使用 Go、Java、Python 等 Kubernetes 客户端库，也应检查库版本是否已经生成或支持 metrics.k8s.io/v1 的类型定义。对于长期维护的内部 SDK，可以将“发现 API 版本、构造资源路径、解析相同数据结构”封装在同一个适配层中，避免业务代码散落 v1beta1 字符串。
升级清单：不要过早下线 v1beta1
对于 Kubernetes v1.37 集群，实际迁移重点可以收敛为以下几项：
- 确认指标实现能够提供
v1.metrics.k8s.io，且对应APIService的状态为可用。 - 让新脚本、新平台服务和直接调用方优先访问
metrics.k8s.io/v1。 - 在迁移期同时提供
v1与v1beta1，避免旧版客户端失效。 - 审核依赖 HPA 的工作负载，不要假设 v1.37 中的 HPA 已自动改用 v1。
- 将资源指标 API 与完整监控、告警、业务指标系统分层建设。
这次稳定化的价值在于降低接口版本风险，而不是增加观测维度。对于集群管理员，最稳妥的动作是验证 metrics-server 或其他实现的 v1 支持；对于应用平台开发者，则应开始将新代码默认指向 metrics.k8s.io/v1，同时为存量集群和旧客户端保留过渡空间。