kubectl top nodes 无法使用快速排查

这个错误：

$ kubectl top nodes
error: Metrics API not available

表示 Kubernetes 的 Metrics Server 没有正常运行或没有被正确注册到 API Server 中，因此 kubectl top 命令无法获取节点或 Pod 的 CPU、内存使用指标。

✅ 一、原因分析

kubectl top 命令依赖 Metrics Server 提供的 /apis/metrics.k8s.io 接口，如果：

• Metrics Server 未安装；
• Metrics Server 启动失败；
• Metrics Server 无法访问 Kubelet（被证书或网络限制）；
• APIService v1beta1.metrics.k8s.io 未处于 Available 状态；

都会导致这个错误。

✅ 二、排查步骤

1. 查看 Metrics Server 是否已部署

kubectl get deployment -n kube-system | grep metrics

如果没有结果，说明还没安装。

2. 查看 Metrics Server Pod 状态

kubectl get pods -n kube-system -l k8s-app=metrics-server

如果 Pod 存在但状态是 CrashLoopBackOff、Pending、Error，可查看详细日志：

kubectl logs -n kube-system -l k8s-app=metrics-server

3. 检查 APIService 是否注册成功

kubectl get apiservice | grep metrics

正常情况下应看到类似：

v1beta1.metrics.k8s.io   kube-system/metrics-server   True    5m

如果 AVAILABLE 列是 False，说明 API 未就绪，可进一步查看原因：

kubectl describe apiservice v1beta1.metrics.k8s.io

✅ 三、解决方法

方式一：安装 Metrics Server（推荐）

如果没有安装，可以直接执行官方安装命令：

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

注： 如果服务拉取镜像失败，可先打开浏览器访问 https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml，将文件下载下来。然后将文件名修改为 metrics-server.yaml，将文件中的镜像修改为国内阿里云的镜像 registry.cn-hangzhou.aliyuncs.com/google_containers/metrics-server:v0.8.0。

如果你的集群在云环境或有自签证书的节点上，可能需要加启动参数让 Metrics Server 忽略证书校验。

修改 Deployment：

kubectl edit deployment metrics-server -n kube-system

在 spec.containers.args 中加入：

- --kubelet-insecure-tls
- --kubelet-preferred-address-types=InternalIP,Hostname,ExternalIP

保存后等待 Pod 重启。

方式二：重新部署或修复

如果已安装但 API 不可用，可尝试：

kubectl delete -n kube-system deployment metrics-server
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

✅ 四、验证

等待 1~2 分钟后再执行：

kubectl top nodes
kubectl top pods -A

如果正常，会输出：

NAME           CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%
k8s-master     250m         6%     1024Mi          40%
k8s-node1      130m         3%     820Mi           30%