Kubernetes v1.37 metrics.k8s.io 稳定后客户端兼容性怎么查

Kubernetes v1.37 把 metrics.k8s.io API 提升到了稳定版 v1，但这不等于所有客户端、Metrics API 实现和 HPA 会在同一时间切换。判断兼容性最稳妥的办法，是依次检查 API 发现结果、v1.metrics.k8s.io 的聚合状态，再用 NodeMetrics 和 PodMetrics 做一次真实请求。

官方资料：https://kubernetes.io/blog/2026/08/27/kubernetes-v1-37-metrics-api-ga/

Metrics v1 参考：https://kubernetes.io/docs/reference/external-api/metrics.v1/

先把 v1.37 的变化范围划清

这次升级首先是“稳定性承诺”的变化，而不是指标采集格式的变化。稳定版接口仍然提供节点和 Pod 的 CPU、内存资源指标，资源类型仍是 NodeMetrics 与 PodMetrics，Pod 指标还包含按容器拆分的 containers 字段。原来的 v1beta1 在 Kubernetes v1.37 过渡期仍可用。

metrics.k8s.io 在Kubernetes v1.37正式进入稳定版后，不需要直接盲升级客户端侧组件，优先对照Kubernetes官方兼容矩阵、你正在用的metrics-server发布页客户端适配说明、本地现有客户端请求返回的API版本字段三个维度交叉校验，就能快速定位兼容范围。

还要分清三个组件：Kubernetes API Server 提供聚合入口，Metrics Server 或其他实现负责提供资源指标，客户端负责选择 API 版本。只升级 API Server 而不升级实际实现，不能凭空得到 metrics.k8s.io/v1。

从 API 发现开始查集群实际支持

第一步不要猜版本，也不要把 kubectl top 能执行当成稳定版已经就绪。先读取 API 组的发现文档：

# 查看集群实际公布的 metrics.k8s.io 版本
kubectl get --raw '/apis/metrics.k8s.io/' | jq .

# 直接请求稳定版节点指标，检查 v1 入口是否能返回资源列表
kubectl get --raw '/apis/metrics.k8s.io/v1/nodes' | jq '{apiVersion, itemCount: (.items | length)}'

如果发现结果只有 v1beta1，说明当前实现还没有把稳定版入口提供出来；这并不表示 v1.37 的 API 本身坏了。若返回 v1 和 v1beta1，则进入下一层，确认聚合服务真的可用。

三层检查把客户端问题定位出来

第二层检查对应的 APIService。它能帮助区分“发现文档里写了 v1”和“API Server 真能把请求转给实现”这两种情况：

# 查看稳定版聚合 API 的可用条件
kubectl get apiservice v1.metrics.k8s.io

# 需要进一步定位时查看条件、服务名和端点
kubectl describe apiservice v1.metrics.k8s.io

如果状态不是 Available=True，重点看后端 Service 是否存在、端点是否有 Pod、Metrics Server 到 Kubelet 的网络是否畅通，以及请求头证书和 RBAC 配置。Metrics API 由聚合层提供，安装了一个名为 Metrics Server 的 Pod，并不自动证明稳定版 API 已被实现。

第三层是资源请求本身。节点和命名空间 Pod 要分别验证，避免只测通一个入口：

# 验证节点指标返回的资源类型和时间窗口
kubectl get --raw '/apis/metrics.k8s.io/v1/nodes' | jq '.apiVersion, .items[0] | {kind, timestamp, window, usage}'

# 验证 default 命名空间中的 Pod 指标
kubectl get --raw '/apis/metrics.k8s.io/v1/namespaces/default/pods' | jq '.apiVersion, .items[0] | {kind, metadata: .metadata.name, containers}'

# 用用户常用入口做一次快速回归；该命令依赖 Metrics Server 正常运行
kubectl top nodes

上面的 kubectl top 适合快速查看近期资源消耗，不适合替代完整监控、历史报表或高精度告警。它展示的数值面向自动伸缩判断，可能与操作系统的 top 不完全相同。

按客户端类型制定迁移和回退策略

兼容策略要按调用方拆开，而不是统一替换字符串：

• kubectl top：使用支持 v1.37 的 kubectl，在集群提供稳定版时优先访问 v1；集群尚未提供时可回退到 v1beta1。
• HPA：不要因为 v1 已稳定就删除 v1beta1。Kubernetes v1.37 的 HPA 控制器仍使用 v1beta1，过渡期应保持该版本可发现、可访问。
• 自研客户端：启动或定期刷新发现结果，优先选择 v1，对旧集群保留 v1beta1 回退；不要把 v1 写死后把“未发现”当成指标为空。
• Metrics API 实现：升级后同时暴露两个版本，并用 APIService 检查聚合状态。具体实现的支持范围要以它自己的兼容矩阵为准。

可以把发布前检查压缩成一张清单：发现接口有目标版本、APIService 为可用、NodeMetrics 与 PodMetrics 请求成功、kubectl top 正常、HPA 仍能读取 v1beta1。五项都满足后，再把自研客户端默认路径切到 v1。

常见问题

metrics.k8s.io v1 稳定后，v1beta1 能立即删除吗？

不建议。v1.37 仍保留 v1beta1，HPA 和旧客户端可能依赖它。等所有调用方完成迁移并确认实现支持后，再按 Kubernetes API 弃用策略规划移除。

APIService 显示可用，但 kubectl top 仍失败怎么办？

继续分别请求 NodeMetrics 和 PodMetrics。若 APIService 正常而资源请求失败，应检查 Metrics Server 到各节点 Kubelet 的地址、端口、证书和网络，而不是反复更换客户端版本。

metrics.k8s.io 能提供业务指标吗？

不能把它当作自定义指标或完整监控系统。它主要服务于节点、Pod 的 CPU/内存资源查看和基于资源的自动伸缩；业务指标应使用适配其 API 的自定义指标或专用监控链路。