AKS 集群离线部署 kube-state-metrics 文档

1. 场景说明

由于 AKS 节点无法直接访问外网镜像仓库或 GitHub，在线执行 Helm 安装时容易出现以下问题：

• Helm 下载 chart 包失败

• GitHub 下载中断，提示 unexpected EOF

• 容器镜像拉取失败

• Pod 状态为 ImagePullBackOff

• Pod 状态为 ErrImagePull

• Pod 状态为 InvalidImageName

因此建议采用：

1. 手动下载 Helm chart 包

2. 使用国内可访问镜像

3. 本地 Helm 安装

---

2. 创建 monitoring 命名空间

kubectl create namespace monitoring --kubeconfig ./kubeconfig.yaml

如果已经存在，可忽略报错。

---

3. 创建 kube-state-metrics 配置文件

创建 kube-state-metrics-values.yaml：

image:
  repository: swr.cn-north-4.myhuaweicloud.com/ddn-k8s/kube-state-metrics
  tag: v2.12.0
  pullPolicy: IfNotPresent

说明：

• repository 使用华为云公共镜像仓库

• 避免默认访问 registry.k8s.io

• tag 使用 v2.12.0

• pullPolicy 设置为 IfNotPresent

---

4. 下载 Helm Chart 包

mkdir -p /root/yy/charts
cd /root/yy/charts

下载 kube-state-metrics chart：

wget https://github.com/prometheus-community/helm-charts/releases/download/kube-state-metrics-7.2.2/kube-state-metrics-7.2.2.tgz

如果下载慢或中断，可以使用断点续传：

wget -c https://github.com/prometheus-community/helm-charts/releases/download/kube-state-metrics-7.2.2/kube-state-metrics-7.2.2.tgz

---

5. 安装 kube-state-metrics

helm install kube-state-metrics ./kube-state-metrics-7.2.2.tgz \
  -n monitoring \
  --kubeconfig ./kubeconfig.yaml \
  -f kube-state-metrics-values.yaml

如果之前安装失败，需要先卸载：

helm uninstall kube-state-metrics -n monitoring --kubeconfig ./kubeconfig.yaml

然后重新执行安装命令。

---

6. 查看部署状态

查看 Pod 状态：

kubectl get pods -n monitoring --kubeconfig ./kubeconfig.yaml

正常状态示例：

NAME                                  READY   STATUS    RESTARTS   AGE
kube-state-metrics-77688b8c87-98z7s   1/1     Running   0          24s

---

7. 查看 Service

kubectl get svc -n monitoring --kubeconfig ./kubeconfig.yaml

通常会看到：

NAME                   TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)
kube-state-metrics     ClusterIP   10.xx.xx.xx     <none>        8080/TCP

---

8. 验证 metrics 接口

查看 Service 名称：

kubectl get svc -n monitoring --kubeconfig ./kubeconfig.yaml

进入任意 Pod 验证：

kubectl run curl-test --rm -it \
  --image=curlimages/curl \
  --restart=Never \
  -n monitoring \
  --kubeconfig ./kubeconfig.yaml -- sh

在容器内执行：

curl http://kube-state-metrics:8080/metrics

如果能看到大量 Prometheus 指标内容，说明部署成功。

---

9. 常见问题

9.1 Helm 下载 chart 报错

报错：

unexpected EOF

处理方式：

wget -c <chart下载地址>

先下载到本地，再使用本地 tgz 包安装。

9.2 Pod 出现 InvalidImageName

报错示例：

invalid reference format

原因：

镜像地址写错，例如错误写成：

repository: registry.k8s.io/swr.cn-north-4.myhuaweicloud.com/ddn-k8s/kube-state-metrics

正确写法：

repository: swr.cn-north-4.myhuaweicloud.com/ddn-k8s/kube-state-metrics

9.3 Pod 出现 ImagePullBackOff

报错示例：

failed to resolve reference

原因：

• 节点无法访问外网镜像仓库

• 镜像地址错误

• Secret 不存在

• 镜像仓库超时

建议优先使用国内公共镜像地址。

---

10. Prometheus 集成建议

后续部署 Prometheus 时，需要关闭其内置 kube-state-metrics，否则会重复部署。

Prometheus values 文件中增加：

kube-state-metrics:
  enabled: false

这样 Prometheus 会直接使用已经部署好的 kube-state-metrics 服务。