摘要

本文记录了一次在已有 Kubernetes 集群中重建 Prometheus + Grafana 监控系统的完整实践:从清理旧监控、选择兼容 K8s 1.23 的 kube-prometheus-stack 版本,到解决镜像拉取、Webhook Job 失败、节点网络异常等问题,最终实现 K8s 集群监控,并成功接入第一台外部云主机,为后续 300 台云主机统一监控打下基础。

背景:为什么要重建监控系统

最初是由于运行多年的zabbix监控系统监控数据出现异常,难以修复且版本老旧。而现有一套运行了两年多的 Kubernetes 集群:

Kubernetes: v1.23.17
节点规模: 3 个 master + 3 个 worker
系统版本: Ubuntu 20.04
容器运行时: Docker
网络插件: Cilium
存储: nfs-csi / nfs-client

集群里原本已经有一套 Prometheus + Grafana,但它存在几个明显问题:

  • Prometheus 是手工 Deployment 部署,不是 kube-prometheus-stack。
  • Prometheus 数据目录使用 emptyDir,Pod 重建后历史数据会丢。
  • 没有完整的 Alertmanager、kube-state-metrics、Prometheus Operator。
  • 历史上有大量 Evicted 的 Prometheus Pod。
  • 后续还希望监控 300 台外部云主机,原方案不适合继续扩展。

因此最终决定:铲掉旧的 Prometheus/Grafana,重新基于 kube-prometheus-stack 搭建一套更规范的监控系统。

对于生产环境,监控系统不要长期停留在“几个 Deployment + ConfigMap”的状态。使用 kube-prometheus-stack 能获得更完整的 Kubernetes 监控能力,也更利于后续维护和升级。

总体方案

最终采用的方案如下:

Kubernetes 集群
  -> kube-prometheus-stack
  -> Prometheus
  -> Grafana
  -> Alertmanager
  -> kube-state-metrics
  -> node-exporter
  -> Prometheus Operator

外部云主机
  -> node_exporter
  -> Prometheus additionalScrapeConfigs
  -> Grafana Node Exporter Dashboard

暴露方式先采用 NodePort,不依赖 Ingress。原因是当时集群里的 ingress-nginx 自身处于异常状态,继续依赖 Ingress 会增加排障复杂度。

访问端口规划:

Grafana:      32000
Prometheus:   32090
Alertmanager: 32093

清理旧监控

旧监控位于 prom 命名空间,确认不再需要旧数据后,直接删除:

kubectl delete ns prom

确认删除完成:

kubectl get ns
kubectl get all -n prom

如果返回:

Error from server (NotFound): namespaces "prom" not found

说明旧命名空间已经删除完成。

选择 kube-prometheus-stack 版本

当前 Kubernetes 版本是 v1.23.17,不能直接使用最新的 kube-prometheus-stack。

当时 Helm 仓库里最新版本已经到 80.x,但对于 K8s 1.23 来说太新。最终选择:

kube-prometheus-stack: 45.31.1
Prometheus Operator:  v0.65.1
Prometheus:           v2.42.0
Grafana:              9.5.2

更新Helm仓库:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

查询版本:

helm search repo prometheus-community/kube-prometheus-stack --versions | grep -E ' *4[5-8]\.' | head -50

拉取 chart:

helm pull prometheus-community/kube-prometheus-stack \
  --version 45.31.1 \
  --destination /data

或者直接下载:

https://github.com/prometheus-community/helm-charts/releases/download/kube-prometheus-stack-45.31.1/kube-prometheus-stack-45.31.1.tgz

后续安装使用本地 chart 包:

/data/kube-prometheus-stack-45.31.1.tgz

这样可以避免 Helm 安装过程中反复访问外网失败。

准备镜像到 Harbor

由于集群访问 registry.k8s.io、quay.io、docker.io 不稳定,需要提前把镜像推到内网 Harbor。

本次用到的镜像包括:

docker pull docker.io/bats/bats:v1.4.1
docker pull docker.io/grafana/grafana:9.5.2
docker pull docker.io/library/busybox:1.31.1
docker pull quay.io/kiwigrid/k8s-sidecar:1.22.0
docker pull quay.io/prometheus/alertmanager:v0.25.0
docker pull quay.io/prometheus/node-exporter:v1.5.0
docker pull quay.io/prometheus-operator/prometheus-operator:v0.65.1
docker pull quay.io/prometheus-operator/prometheus-config-reloader:v0.65.1
docker pull quay.io/prometheus/prometheus:v2.42.0
docker pull registry.k8s.io/ingress-nginx/kube-webhook-certgen:v20221220-controller-v1.5.1-58-g787ea74b6
docker pull registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.8.2

推送到 Harbor 后,镜像路径统一为:

harbor.zspt.com/devops/...

基础版 monitoring-values.yaml

下面是基础监控栈使用的 /data/monitoring-values.yaml。这一版先完成 Kubernetes 集群自身监控,不提前接入外部云主机;外部主机的 additionalScrapeConfigsSecret 放到安装完成后再追加。

fullnameOverride: kube-prometheus-stack

grafana:
  enabled: true
  adminPassword: "admin123456"

  image:
    repository: harbor.zspt.com/devops/grafana/grafana
    tag: "9.5.2"

  service:
    type: NodePort
    nodePort: 32000

  persistence:
    enabled: true
    type: pvc
    storageClassName: nfs-csi
    accessModes:
      - ReadWriteOnce
    size: 10Gi

  initChownData:
    image:
      repository: harbor.zspt.com/devops/library/busybox
      tag: "1.31.1"

  sidecar:
    image:
      repository: harbor.zspt.com/devops/kiwigrid/k8s-sidecar
      tag: "1.22.0"

  testFramework:
    image: harbor.zspt.com/devops/bats/bats
    tag: "v1.4.1"

prometheus:
  service:
    type: NodePort
    nodePort: 32090
  prometheusSpec:
    image:
      registry: harbor.zspt.com
      repository: devops/prometheus/prometheus
      tag: "v2.42.0"
    scrapeInterval: 30s
    scrapeTimeout: 10s
    evaluationInterval: 30s
    retention: 15d
    retentionSize: 80GB
    storageSpec:
      volumeClaimTemplate:
        spec:
          storageClassName: nfs-csi
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 100Gi
    resources:
      requests:
        cpu: "1"
        memory: 4Gi
      limits:
        cpu: "4"
        memory: 8Gi

alertmanager:
  enabled: true
  service:
    type: NodePort
    nodePort: 32093
  alertmanagerSpec:
    image:
      registry: harbor.zspt.com
      repository: devops/prometheus/alertmanager
      tag: "v0.25.0"
    storage:
      volumeClaimTemplate:
        spec:
          storageClassName: nfs-csi
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 5Gi
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 500m
        memory: 512Mi

prometheusOperator:
  enabled: true
  image:
    registry: harbor.zspt.com
    repository: devops/prometheus-operator/prometheus-operator
    tag: "v0.65.1"
  prometheusConfigReloader:
    image:
      registry: harbor.zspt.com
      repository: devops/prometheus-operator/prometheus-config-reloader
      tag: "v0.65.1"
  admissionWebhooks:
    enabled: true
    patch:
      enabled: true
      image:
        registry: harbor.zspt.com
        repository: devops/ingress-nginx/kube-webhook-certgen
        tag: "v20221220-controller-v1.5.1-58-g787ea74b6"

prometheus-node-exporter:
  image:
    registry: harbor.zspt.com
    repository: devops/prometheus/node-exporter
    tag: "v1.5.0"

kube-state-metrics:
  image:
    registry: harbor.zspt.com
    repository: devops/kube-state-metrics/kube-state-metrics
    tag: "v2.8.2"

nodeExporter:
  enabled: true

kubeStateMetrics:
  enabled: true

defaultRules:
  create: true

这里有几个关键点:

  • Prometheus PVC 从 50Gi 提升到 100Gi。
  • Prometheus 内存上限从 4Gi 提升到 8Gi。
  • scrapeInterval 使用 30s,适合后续 300 台主机接入。
  • 外部云主机通过后续追加的 additionalScrapeConfigsSecret 接入。
  • 所有镜像都改成 Harbor 地址,避免安装时访问外网失败。

安装前渲染检查

安装前先渲染 YAML:

helm template kube-prometheus-stack /data/kube-prometheus-stack-45.31.1.tgz \
  -n monitoring \
  -f /data/monitoring-values.yaml \
  > /tmp/kube-prometheus-stack-rendered.yaml

检查镜像是否全部来自 Harbor:

grep -E 'image:' /tmp/kube-prometheus-stack-rendered.yaml | sort -u

检查 API 版本是否兼容 K8s 1.23:

grep -E '^apiVersion:' /tmp/kube-prometheus-stack-rendered.yaml | sort | uniq

确认没有旧 API:

grep -E 'extensions/v1beta1|networking.k8s.io/v1beta1|policy/v1beta1' /tmp/kube-prometheus-stack-rendered.yaml

没有输出即可继续。

安装 kube-prometheus-stack

执行安装:

kubectl create ns monitoring

helm install kube-prometheus-stack /data/kube-prometheus-stack-45.31.1.tgz \
  -n monitoring \
  -f /data/monitoring-values.yaml \
  --timeout 15m

检查状态:

helm list -n monitoring
kubectl -n monitoring get pod -o wide
kubectl -n monitoring get svc
kubectl -n monitoring get pvc

正常结果应该包括:

Grafana:       Running
Prometheus:    Running
Alertmanager:  Running
node-exporter: Running
kube-state-metrics: Running
operator: Running

服务端口:

Grafana:      http://10.0.5.21:32000
Prometheus:   http://10.0.5.21:32090
Alertmanager: http://10.0.5.21:32093

Grafana 默认登录:

用户名: admin
密码: admin123456

接入外部云主机

基础监控栈安装完成后,再接入第一台外部云主机。这样流程更清晰:先确保 Prometheus/Grafana 自身运行正常,再通过 additionalScrapeConfigs 扩展外部 target。

第一台外部云主机 IP 是:

10.0.5.56

安装 node_exporter

外部云主机安装 node_exporter 的方式如下:

cd /opt

wget https://github.com/prometheus/node_exporter/releases/download/v1.5.0/node_exporter-1.5.0.linux-amd64.tar.gz

tar -xzf node_exporter-1.5.0.linux-amd64.tar.gz

cp node_exporter-1.5.0.linux-amd64/node_exporter /usr/local/bin/

创建运行用户:

useradd --no-create-home --shell /usr/sbin/nologin node_exporter

chown node_exporter:node_exporter /usr/local/bin/node_exporter

创建 systemd 服务:

cat > /etc/systemd/system/node_exporter.service <<'EOF'
[Unit]
Description=Prometheus Node Exporter
After=network.target

[Service]
User=node_exporter
Group=node_exporter
Type=simple
ExecStart=/usr/local/bin/node_exporter --web.listen-address=:9100
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

启动服务:

systemctl daemon-reload
systemctl enable --now node_exporter
systemctl status node_exporter

本机验证:

curl http://127.0.0.1:9100/metrics | head

从 K8s 节点验证:

curl http://10.0.5.56:9100/metrics | head

创建外部主机 scrape 配置

确认 node_exporter 可访问后,创建 Prometheus 的额外抓取配置。

为了复用默认的 Node Exporter Dashboard,job_name 不单独命名为 external-cloud-node,而是统一使用默认看板里写死的:

node-exporter

/data/additional-scrape-configs.yaml 内容如下:

- job_name: node-exporter
  static_configs:
    - targets:
        - 10.0.5.56:9100
      labels:
        group: cloud
        env: zwsp
        source: external

创建 Secret:

kubectl -n monitoring delete secret additional-scrape-configs --ignore-not-found

kubectl -n monitoring create secret generic additional-scrape-configs \
  --from-file=additional-scrape-configs.yaml=/data/additional-scrape-configs.yaml

然后在 /data/monitoring-values.yaml 的 prometheus.prometheusSpec 下追加:

    additionalScrapeConfigsSecret:
      enabled: true
      name: additional-scrape-configs
      key: additional-scrape-configs.yaml

通过 Helm 升级让配置生效:

helm upgrade kube-prometheus-stack /data/kube-prometheus-stack-45.31.1.tgz \
  -n monitoring \
  -f /data/monitoring-values.yaml \
  --timeout 15m

如果 Prometheus 页面中看到:

node-exporter
10.0.5.56:9100
UP

说明外部云主机已经接入成功。

如果后续新增主机,只需要更新 /data/additional-scrape-configs.yaml、重建 Secret,并再次执行 helm upgrade。

Grafana 看板适配

安装完成后,Grafana 默认会带一些 Node Exporter Dashboard,例如:

Node Exporter / Nodes
Node Exporter / USE Method / Node

一开始我将外部主机的 job 命名成了:

external-cloud-node

Prometheus 能抓到数据,但 Grafana 默认看板没有数据。原因是这些看板里的 PromQL 写死了:

job="node-exporter"

例如 CPU 面板中类似:

node_cpu_seconds_total{job="node-exporter", instance="$instance"}

因此,最佳做法不是逐个修改面板,而是让外部主机也使用相同的 job_name:

job_name: node-exporter

这样外部主机就能直接复用默认 Dashboard。

不要为了接入外部主机去手工改几十个 Grafana 面板。更推荐统一 Prometheus 标签和 job 命名,让 Dashboard 自然复用。

最终效果:

踩坑与避坑指南

坑一:最新版 chart 不一定适合旧 K8s

当前 K8s 是 1.23.17,而 kube-prometheus-stack 最新版本已经到 80+。直接安装最新版可能带来 API 兼容性问题。

最终选择 45.31.1,它的 Operator 版本是 v0.65.1,对 K8s 1.23 更稳妥。

坑二:Helm install 时下载失败

曾经遇到:

Error: INSTALLATION FAILED: failed to download "prometheus-community/kube-prometheus-stack" at version "45.31.1"

解决方式是先 helm pull 到本地:

helm pull prometheus-community/kube-prometheus-stack \
  --version 45.31.1 \
  --destination /data

然后使用本地 .tgz 安装:

helm install kube-prometheus-stack /data/kube-prometheus-stack-45.31.1.tgz \
  -n monitoring \
  -f /data/monitoring-values.yaml

坑三:registry.k8s.io 镜像拉取失败

安装时 admission webhook Job 拉取镜像失败:

Failed to pull image "registry.k8s.io/ingress-nginx/kube-webhook-certgen:..."

解决方式是把所有镜像提前同步到 Harbor,并在 monitoring-values.yaml 中覆盖镜像地址。

坑四:Grafana chart 的镜像配置格式不一致

一开始把 Grafana 镜像写成了:

image:
  registry: harbor.zspt.com
  repository: devops/grafana/grafana
  tag: "9.5.2"

渲染后发现镜像变成:

devops/grafana/grafana:9.5.2

没有带 harbor.zspt.com。

Grafana 子 chart 这里需要写成:

image:
  repository: harbor.zspt.com/devops/grafana/grafana
  tag: "9.5.2"

另外 grafana.testFramework.image 是字符串,不是 map。错误写法会渲染出:

map[registry:harbor.zspt.com repository:devops/bats/bats tag:v1.4.1]:v1.4.1

正确写法是:

testFramework:
  image: harbor.zspt.com/devops/bats/bats
  tag: "v1.4.1"

坑五:worker-3 Pod 网络异常导致 Webhook Job 失败

安装时 admission Job 一直失败,日志如下:

Get "https://10.96.0.1:443/api/v1/namespaces/monitoring/secrets/kube-prometheus-stack-admission": dial tcp 10.96.0.1:443: i/o timeout

测试发现:

kubectl -n monitoring exec api-test-worker3 -- wget -S -O- --timeout=5 https://10.96.0.1:443

结果是 timeout。

而在 worker-2 上测试:

HTTP/1.1 403 Forbidden

这说明 worker-2 网络是通的,只是没有认证;worker-3 才是真正网络不通。

临时处理方式:

kubectl cordon k8s-worker-3

然后重新安装。这样普通 Pod 不会再调度到 worker-3,安装成功。

需要注意,node-exporter 是 DaemonSet,仍然会跑到 worker-3 上,这是正常的。

坑六:controller-manager、scheduler、etcd 显示 DOWN

Prometheus Targets 中曾看到:

kube-controller-manager 0/3 up
kube-scheduler          0/3 up
kube-etcd               0/3 up

这是 kubeadm 集群常见现象,不代表 Prometheus 安装失败。

通常原因是:

controller-manager 和 scheduler metrics 默认监听 127.0.0.1
etcd metrics 可能需要额外证书、端口和 ServiceMonitor 配置

第一阶段可以先不处理,核心监控先跑起来。后续再专门修 scheduler、controller-manager、etcd 的 metrics 暴露。

300 台云主机能不能扛住

只监控 node_exporter,300 台对单实例 Prometheus 来说不算大,但要做好资源规划。

本次配置做了几项调整:

scrapeInterval: 30s
scrapeTimeout: 10s
retention: 15d
retentionSize: 80GB
storage: 100Gi
memory limit: 8Gi

如果后续还要接入 MySQL、Redis、Nginx、JVM 等 exporter,需要继续观察 Prometheus 的资源指标。

建议重点关注:

prometheus_tsdb_head_series
rate(prometheus_tsdb_head_samples_appended_total[5m])
prometheus_target_scrape_pool_targets
process_resident_memory_bytes

接入顺序建议分批:

第一批:5 台
第二批:30 台
第三批:100 台
第四批:300 台

不要一次性把所有主机加入,避免问题定位困难。

总结

这次实践的核心把 Prometheus 升级成一套更适合长期维护的 Kubernetes 监控栈。

最终方案具备几个优点:

  • 使用 kube-prometheus-stack,组件完整。
  • 所有镜像走 Harbor,适合内网环境。
  • Prometheus 使用 PVC 持久化,避免数据随 Pod 丢失。
  • 通过 additionalScrapeConfigs 接入外部云主机。
  • 统一使用 job_name: node-exporter,复用默认 Grafana Dashboard。
  • 为后续 300 台云主机接入预留了资源和标签规范。