结论：kubectl top 报错或返回空，90% 是 metrics-server 未真正就绪——关键看 kubectl get apiservice v1beta1.metrics.k8s.io 的 available 是否为 true；若为 false，需检查聚合层配置、kubelet 连通性及证书校验问题。
直接说结论： kubectl top 报错或返回空，90% 是 metrics-server 没真正“活”起来——它可能 Pod 在运行，但 API 未注册、证书握手失败、或 kube-apiserver 缺少聚合层支持。
检查 v1beta1.metrics.k8s.io 是否可用
这是最直接的判断依据。Metrics Server 的功能不是靠 Pod 状态决定的，而是看这个聚合 API 是否被 kube-apiserver 正确代理。
- 运行
kubectl get apiservice v1beta1.metrics.k8s.io - 重点看
AVAILABLE列：必须是True，否则整个kubectl top链路就断了 - 如果显示
False，立刻执行kubectl describe apiservice v1beta1.metrics.k8s.io，看Conditions下的Reason和Message—— 常见的是FailedDiscoveryCheck（后端不可达）或MissingEndpoints（Service 没关联到 Pod）
确认 metrics-server Pod 能连通 kubelet
Metrics Server 启动后，会主动轮询每个节点的 kubelet Summary API（默认 https://<node-ip>:10250/metrics/resource</node-ip>）。一旦证书或网络不通，它就会静默失败，Pod 状态仍为 Running，但日志里全是 403 或 x509 错误。
- 先查日志：
kubectl logs -n kube-system -l k8s-app=metrics-server --tail=50 - 高频错误包括：
x509: certificate signed by unknown authority、no routes found to host、403 Forbidden - 若报证书问题，说明 kubelet 使用了自签证书，而 metrics-server 默认校验；需在 Deployment 的
args中加--kubelet-insecure-tls（仅测试环境）或配置正确的 CA 文件（生产环境） - 若报连接超时，检查节点防火墙是否放行 10250 端口，以及 kubelet 是否启用了
--read-only-port=0（这会禁用 Summary API）
二进制部署集群必须开启 API 聚合层
如果你是用 kubeadm 以外的方式（比如手搭二进制高可用集群），kube-apiserver 默认不启用聚合层（Aggregation Layer），这时即使 metrics-server 部署成功，v1beta1.metrics.k8s.io 也永远无法注册。
- 检查
kube-apiserver启动参数中是否包含：--requestheader-client-ca-file、--proxy-client-cert-file、--proxy-client-key-file、--runtime-config=api/all=true - 缺少任一参数都会导致
apiservice卡在False状态，且kubectl describe显示reason: FailedDiscoveryCheck+message: failing or missing - 修改后必须重启
kube-apiserver（不是 reload），并等待所有 master 节点同步完成
最容易被忽略的一点：API 聚合层依赖一套独立的证书链（proxy-client 证书），它和集群 CA 完全无关。很多运维同学只配了 --requestheader-client-ca-file，却忘了生成和分发 proxy-client.crt/key，结果 metrics-server 的请求始终被 apiserver 拒绝，日志里却没有任何明确提示。
