Skip to content

title: Helm 部署 Prometheus：kube-prometheus-stack 六步跑通 + 3 个 K8s 新手必踩坑 description: Helm 部署 Prometheus 完整教程：kube-prometheus-stack 是什么、六步实操、ServiceMonitor 接入真实应用、Grafana 登录与告警规则。含 3 个 K8s 新手必踩坑。 tags: [prometheus, helm, kubernetes, k8s-monitoring] lang: zh date: 2026-10-22 answer: | K8s 集群监控首选 kube-prometheus-stack：一个 Helm Chart 装 6 个组件（Prometheus + Grafana + Alertmanager + node-exporter + kube-state-metrics + Operator）。六步：装 Helm → 建 namespace → 加 repo → helm install → 验证 pod → 加 ServiceMonitor。 K8s 新手必踩 3 个坑：Grafana 默认密码是 prom-operator（不是 admin）、CRD 装不上导致所有 pod Pending、ServiceMonitor 没打 release label Prometheus 找不到。 faq: - q: kube-prometheus-stack 和普通 prometheus 有什么区别？ a: 一个是完整栈（含 Grafana、Alertmanager、node-exporter、kube-state-metrics、Prometheus Operator），一个是纯 Prometheus 二进制。栈用 Helm 装、通过 CRD 管理配置，Prometheus 二进制要手写 YAML 且不含告警。K8s 场景必用栈，别用二进制。 - q: Grafana 装完默认密码是什么？ a: kube-prometheus-stack 的默认密码是 prom-operator，不是官方 Grafana 的 admin。admin 用户名不变。登录立刻改，kubectl get secret -n monitoring -o jsonpath="{.data.admin-password}" kube-prometheus-stack-grafana | base64 -d 可以取到实际密码。 - q: ServiceMonitor 建了但 Prometheus 抓不到目标？ a: 99% 是 label 不匹配。kube-prometheus-stack 默认只抓带 release: monitoring 标签的 Service。你的 ServiceMonitor 要加 labels: release: monitoring（值必须是 helm install 时 --name 的值），或者改 values 里的 prometheus.serviceMonitorSelectorNilUsesHelmValues。

Helm 部署 Prometheus：kube-prometheus-stack 六步跑通 + 3 个 K8s 新手必踩坑

Prometheus 单机装法我之前写过了（Prometheus 部署实战），单机够用但一到 K8s 集群就不实用——你不可能在一台 K8s 节点上跑 Prometheus 然后去抓其他节点的 target。K8s 集群监控的正确姿势是 kube-prometheus-stack，一个 Helm Chart 装一整套，含 Prometheus、Grafana、Alertmanager、node-exporter、kube-state-metrics 和 Prometheus Operator。

这篇文章讲怎么从零装起来，然后接入一个真实应用做监控，最后配一条告警规则。K8s 新手必踩的 3 个坑都在最后，装之前先看能省一小时。

概念：kube-prometheus-stack 到底装了什么

装之前先搞清楚 Helm Chart 里都包含哪些组件。搞不清就容易装完找不到 Grafana：

组件 作用 端口
prometheus 抓指标、存 TSDB、跑 PromQL 9090
grafana 可视化仪表盘 3000
alertmanager 告警路由、去重、通知 9093
node-exporter 节点 CPU/内存/磁盘指标 9100
kube-state-metrics K8s 对象状态（Pod、Deployment、PVC） 8080
prometheus-operator 通过 CRD 管理 Prometheus 配置 8080

Prometheus Operator 是核心——它把 Prometheus 配置、告警规则、ServiceMonitor 都变成 K8s CRD，你不需要手动 restart Prometheus 加载配置。CRD 就是 Custom Resource Definition，K8s 的扩展机制。

6 步实操

步骤 1：装 Helm 3

# 检查 helm 是否已装
helm version

# 未装则按官方文档装（略）
# https://helm.sh/docs/intro/install/

你应该看到什么：version.BuildInfo{Version:"v3.x.x"...}。Helm 3 是当前主流，Helm 2 已经 EOL。

步骤 2：建 monitoring namespace

kubectl create namespace monitoring
kubectl get ns monitoring

你应该看到什么：monitoring Active 0s。

为什么单独一个 namespace：K8s 生产实践强烈建议工具类组件（Prometheus、Grafana）与业务分开。namespace 是 K8s 的资源隔离单位，也方便后续 RBAC 授权。

步骤 3：加 Helm repo

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

# 看有哪些 chart
helm search repo prometheus-community/ | head -20

你应该看到什么：末尾输出大量 chart 名，包括 prometheus-community/kube-prometheus-stack。

步骤 4：写 values.yaml（关键！）

默认 values 装出来 Grafana 密码是 prom-operator，retention 15 天，存储无持久化。生产环境建议改：

# values.yaml

# Grafana 改密码
grafana:
  adminPassword: "CHANGE_ME_to_a_strong_password"

# Prometheus 保留期 + 存储
prometheus:
  prometheusSpec:
    retention: 30d
    retentionSize: 20GB
    storageSpec:
      volumeClaimTemplate:
        spec:
          accessModes: ["ReadWriteOnce"]
          storageClassName: standard    # 按你的集群实际 storageClass 改
          resources:
            requests:
              storage: 20Gi
    resources:
      requests:
        memory: 2Gi
        cpu: 1000m
      limits:
        memory: 4Gi
        cpu: 2000m
    # 抓自己
    ruleStorage:
      volumeClaimTemplate:
        spec:
          accessModes: ["ReadWriteOnce"]
          storageClassName: standard
          resources:
            requests:
              storage: 5Gi

# Alertmanager 告警通道
alertmanager:
  alertmanagerSpec:
    config:
      receivers:
        - name: "wechat-webhook"
          webhook_configs:
            - url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
              send_resolved: true
      route:
        receiver: "wechat-webhook"
        group_by: ["alertname", "namespace"]
        group_wait: 30s
        group_interval: 5m
        repeat_interval: 4h

# 装
helm install monitoring prometheus-community/kube-prometheus-stack \
  -n monitoring \
  -f values.yaml \
  --timeout 10m

你应该看到什么：NAME: monitoring / STATUS: deployed / REVISION: 1。

步骤 5：验证 Pod 就绪

# 等所有 pod Ready
kubectl wait --for=condition=Ready pods --all -n monitoring --timeout=300s

# 看 pod 状态
kubectl get pods -n monitoring

你应该看到什么：一堆 pod 都是 Running 状态，READY 列都是 1/1 或 2/2。

# 看 Prometheus Targets
kubectl port-forward -n monitoring svc/monitoring-prometheus 9090:9090 &

# 浏览器打开 http://localhost:9090/targets

你应该看到什么：Targets 页面所有 job 都是绿色 UP 状态。

步骤 6：接入真实应用（ServiceMonitor）

装完 kube-prometheus-stack 只能监控 K8s 自己。要监控你自己的业务应用，得写 ServiceMonitor。假设你的应用已有一个 Service 暴露 /metrics：

# app-servicemonitor.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: demo-app-monitor
  namespace: monitoring
  labels:
    release: monitoring      # 关键！必须是 helm install 时的 release name
spec:
  selector:
    matchLabels:
      app: demo-app
      # namespace 匹配需要在别的字段指定，见下
  endpoints:
    - port: http              # Service 里 targetPort 对应的 name
      path: /metrics
      interval: 30s
  namespaceSelector:
    any: true
    matchNames:
      - default               # 你的应用所在 namespace

kubectl apply -f app-servicemonitor.yaml

# 30 秒后看 Prometheus Targets 有没有 demo-app
kubectl port-forward -n monitoring svc/monitoring-prometheus 9090:9090 &
# 浏览器 http://localhost:9090/targets 搜索 demo-app

你应该看到什么：Targets 页面出现 demo-app job，状态绿色 UP。

# 在 Grafana 里查一下数据
kubectl port-forward -n monitoring svc/monitoring-grafana 3000:80 &
# 打开 http://localhost:3000 登录，Explore 页写 PromQL

rate(http_requests_total{job="demo-app"}[5m])

看到有数就成功。

3 个 K8s 新手必踩坑

坑一：Grafana 密码错了登不进去

症状：浏览器打开 Grafana 页面，用 admin/admin 登录报 "Invalid credentials"。

根因：kube-prometheus-stack 默认密码是 prom-operator，不是官方 Grafana 的 admin。

验证：

kubectl get secret -n monitoring monitoring-grafana \
  -o jsonpath="{.data.admin-password}" | base64 -d

你应该看到什么：返回一串明文密码，默认是 prom-operator。

修复：立即改密码，或者装的时候用 --set grafana.adminPassword=your_password。

坑二：所有 pod Pending（CRD 未装）

症状：helm install 成功，但 kubectl get pods 显示多个 pod Pending 或 ContainerCreating 卡住。

排查：

kubectl describe pod <pending-pod> -n monitoring

你应该看到什么：末尾 Events 里有 FailedCreate: pods "xxx" is forbidden: no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"。

根因：kube-prometheus-stack 依赖一堆 CRD（ServiceMonitor、PrometheusRule、PodMonitor 等）。如果 K8s 版本太老（1.19 以下）或 CRD 安装失败，所有 pod 都会 Pending。

修复：

# 单独装 CRD
helm install monitoring prometheus-community/kube-prometheus-stack \
  -n monitoring \
  --set crds.enabled=true \
  -f values.yaml

# 或确认 K8s 版本 ≥ 1.22
kubectl version --short

坑三：ServiceMonitor 建了 Prometheus 找不到

症状：ServiceMonitor kubectl get servicemonitor 有输出，但 Prometheus Targets 里搜不到对应 job。

根因：ServiceMonitor 的 label 与 Prometheus 的 selector 不匹配。kube-prometheus-stack 默认 prometheus.serviceMonitorSelectorNilUsesHelmValues: true，即只选带 release: monitoring 标签的 ServiceMonitor。

排查：

kubectl get servicemonitor -n monitoring -o yaml | grep -A 3 labels

你应该看到什么：每个 ServiceMonitor 都应有 labels: release: monitoring。

修复：

metadata:
  labels:
    release: monitoring   # 加这一行

或者改 values：

prometheus:
  serviceMonitorSelectorNilUsesHelmValues: false
  serviceMonitorNamespaceSelector: {}

权衡：false 会抓到所有 namespace 的 ServiceMonitor，灵活但可能暴露过多 target。生产建议保留默认 true 并显式打 label。

告警规则：PrometheusRule CRD

装完就能配告警，不用改 Prometheus 的 prometheus.yml：

# app-alerts.yaml
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: demo-app-alerts
  namespace: monitoring
  labels:
    release: monitoring
spec:
  groups:
    - name: demo-app.rules
      interval: 30s
      rules:
        - alert: DemoAppDown
          expr: up{job="demo-app"} == 0
          for: 2m
          labels:
            severity: critical
            team: backend
          annotations:
            summary: "demo-app 挂了"
            description: "demo-app 已经 2 分钟没有响应，最后抓取时间 {{ $labels.instance }}"

        - alert: DemoAppHighLatency
          expr: |
            histogram_quantile(0.95,
              rate(http_request_duration_seconds_bucket{job="demo-app"}[5m])
            ) > 1
          for: 10m
          labels:
            severity: warning
          annotations:
            summary: "demo-app P95 延迟超 1s"
            description: "过去 10 分钟 P95 请求延迟超过 1 秒，当前 {{ $value }}s"

kubectl apply -f app-alerts.yaml

# 验证规则已加载
kubectl port-forward -n monitoring svc/monitoring-prometheus 9090:9090 &
# 浏览器 http://localhost:9090/rules 搜索 DemoApp

你应该看到什么：Rules 页面出现 DemoAppDown 和 DemoAppHighLatency 两条规则，状态 firing: false（说明当前没触发）。

Cheat Sheet：Helm 部署常用命令

# 命令 用途
1 helm list -n monitoring 看已装的 Chart
2 helm status monitoring -n monitoring 看 Chart 状态
3 helm get values monitoring -n monitoring 看实际生效的 values
4 helm get manifest monitoring -n monitoring 看渲染出的完整 YAML
5 helm upgrade monitoring ... -f values.yaml 升级 Chart
6 helm history monitoring -n monitoring 看版本历史
7 helm rollback monitoring <rev> -n monitoring 回滚
8 helm uninstall monitoring -n monitoring 卸载
9 kubectl port-forward -n monitoring svc/monitoring-grafana 3000:80 本地访问 Grafana
10 kubectl port-forward -n monitoring svc/monitoring-prometheus 9090:9090 本地访问 Prometheus
11 kubectl logs -n monitoring -l app.kubernetes.io/name=prometheus -f 看 Prometheus 日志
12 kubectl get servicemonitor -A 看所有 ServiceMonitor
13 kubectl get prometheusrule -A 看所有告警规则
14 kubectl get alertmanager -n monitoring 看 Alertmanager CRD
15 kubectl delete pvc -n monitoring -l app.kubernetes.io/name=prometheus 清 Prometheus 数据（慎用）

收尾：什么场景该选 Helm，什么场景不该选

该选 kube-prometheus-stack 的场景： - 已有 K8s 集群，1.22+ 版本 - 有运维能力，能读 CRD YAML - 需要 K8s 对象状态指标（kube-state-metrics） - 需要 GitOps 管理（所有配置都是 YAML）

不该选的场景： - 单机 / 少量虚拟机 → 用 Docker 装法 更简单 - 需要 Windows 监控 → 用 Zabbix，Prometheus 生态没好的 Windows exporter - 已经买了 Datadog / New Relic → 别重复造轮子

我个人倾向 kube-prometheus-stack，但坦率说它踩坑门槛比 Docker 装法高——CRD 概念、values 覆盖、ServiceMonitor 选择器这些都要理解到位。装完之后维护成本也不低，尤其是 Prometheus 版本升级、CRD 兼容性这些坑会时不时冒出来。能不能省时间，取决于团队对 K8s 的熟悉程度。

延伸阅读