Kubernetes 1.37 Metrics API 晋级稳定：kubectl top 与自动扩缩容如何评估

Kubernetes 1.37 的 Metrics API 晋级稳定，真正值得关注的是资源观测链路终于有了更清晰的版本边界。它提供节点和 Pod 的 CPU、内存用量，是 kubectl top 与基于资源指标的自动扩缩容共同依赖的数据入口。升级时先验证 APIService、采集器和权限，再看 HPA 是否拿到新鲜数据，通常比只看控制面版本更稳妥。

结论是：Metrics API 稳定化降低了接口契约的不确定性，但不会替你修复 metrics-server 不可用、证书失败或资源指标延迟；生产验收仍要沿着“采集—聚合 API—kubectl top—HPA”逐段检查。

Kubernetes 1.37 这次稳定化到底改变了什么

Kubernetes 官方在 2026 年 8 月 27 日的专题文章中说明，v1.37 将 Metrics API 推进到稳定的 metrics.k8s.io/v1。这个 API 暴露节点和 Pod 的 CPU、内存使用量，kubectl top 与资源指标型 HPA 都会从这里取数。它是观测链路的契约收敛，不是一个新的监控存储系统。

因此，升级判断要拆成两件事：API 版本是否稳定，以及当前集群能否持续提供可信数据。前者看 Kubernetes 版本和 API 注册状态，后者看采集器日志、时间戳、权限和扩缩容事件。

先把采集到扩缩容的链路画清楚

一条可验收的路径应当是：metrics-server 从 kubelet 获取 CPU、内存样本，注册为 metrics.k8s.io APIService，聚合层把数据提供给 kubectl top 和 HPA 控制器。任一环节失败，最后的 Pod 副本数都可能停在旧值。

这条链路里，kubectl top 是人工查询点，HPA 是自动决策点。先从人工查询点确认数据，再看 HPA，是因为前者更容易区分“没有指标”和“扩缩容条件未满足”。

升级前后用四个检查点确认数据没有断

1. 看 APIService 是否可用

kubectl get apiservice v1beta1.metrics.k8s.io
kubectl get --raw "/apis/metrics.k8s.io/v1" | head

集群具体发行版可能仍保留兼容的旧注册入口，验收时以当前组件文档和实际响应为准。重点不是命令返回一行，而是 APIService 的 AVAILABLE 状态以及响应是否包含节点或 Pod 资源对象。

2. 用 kubectl top 观察时间戳和对象范围

kubectl top nodes
kubectl top pods -A --sort-by=cpu

至少等待一次采集周期后再判断。正常结果应能看到节点或 Pod 的 CPU、内存用量，并且数据不是长时间停留在同一个采集时刻；若命令报 “Metrics API not available”，先查采集器与 APIService，不要直接修改 HPA 阈值。

3. 检查 metrics-server 的采集日志

kubectl -n kube-system logs deploy/metrics-server --since=10m

这里要找的是 kubelet 访问失败、证书校验失败、地址解析失败和权限拒绝等具体证据。单次超时不必马上回滚，但连续多个采集周期没有成功样本，就不能把这次升级标记为通过。

4. 把 HPA events 与指标读数对上

kubectl describe hpa checkout-api -n production
kubectl get hpa checkout-api -n production -o wide

成功验收至少能在 HPA 状态中看到当前指标、目标值和期望副本数，events 不应持续出现指标读取失败。kubectl top 有数据而 HPA 仍异常，常见原因是目标资源请求未配置、命名空间/名称选错或控制器权限不足。

稳定 API 不等于可以立刻放开自动扩缩容

资源指标只回答 CPU 或内存用了多少，不回答队列积压、请求延迟或业务错误率。一个结账服务可能 CPU 还低，但下游队列已经堆积；此时只依赖资源型 HPA，扩容动作会滞后。Metrics API 稳定后，可以把它作为可靠的基础信号，再与业务指标型扩缩容方案组合。

另一个容易忽略的边界是数据新鲜度。HPA 控制器拿到的是采集器转发的样本，不是每个容器的实时计数器。升级后的第一轮灰度应记录采集时间、HPA 当前指标、期望副本数和实际副本数，观察它们是否按预期变化。

面向团队的升级决策清单

相关问题

kubectl top 正常，为什么 HPA 还是拿不到指标？

两者查询路径相近但不完全等价。应检查 HPA 的目标对象、资源请求字段、控制器 events 和命名空间，确认不是目标配置问题。

Metrics API 稳定后还需要 metrics-server 吗？

稳定的是 API 契约，不是采集实现。集群仍需要一个能从 kubelet 提供节点和 Pod 指标的组件，具体部署方式要遵循发行版文档。

只看 CPU 能设计好自动扩缩容吗？

不能。CPU 适合反映一类计算压力，队列长度、延迟和错误率等业务信号可能更早暴露容量风险。

最后的验收顺序

把验收固定成“APIService 可用—kubectl top 有新鲜数据—采集日志无连续错误—HPA 状态和 events 正常—灰度负载下副本数符合预期”。其中任何一段没有证据，就把结果记为待处理，而不是用 Kubernetes 1.37 的稳定标签替代现场验证。