在 kubeadm 部署的 Kubernetes 集群上安装 kube-prometheus 监控栈

• 云原生
• 可观测性
• 指标监控
• 监控大盘
• 告警

导读

本文是 kube-prometheus 项目官方指南《Deploy to kubeadm》的完整技术解读与实践手册。它面向使用 kubeadm 自托管 Kubernetes 集群的用户，说明如何调整控制面组件监听地址、暴露kube-controller-manager与kube-scheduler的指标端点，并基于本仓库的manifests目录一步一步安装 Prometheus、Prometheus Operator、Alertmanager、node-exporter、kube-state-metrics 与 Grafana。读完本文，你将掌握：kubeadm 集群部署前需要做的控制面暴露配置、kube-prometheus 各监控数据源（Metric Sources）的采集原理、一条从零到可访问三套 UI 的完整安装命令链，以及对应的仓库源码与配置文件佐证。

一、为什么在 kubeadm 集群上监控需要额外配置

kubeadm 是 Kubernetes 官方推荐的、用于部署与管理自托管集群的工具，它会自动完成很多通用配置，让用户快速获得一个可用的集群。但默认情况下，kubeadm 存在两个与监控直接相关的限制：

1. kube-controller-manager与kube-scheduler以静态 Pod 形式运行在控制面节点上，并且只监听127.0.0.1。这意味着它们暴露的/metrics端点无法被集群内其他命名空间的组件访问，Prometheus 的 ServiceMonitor 也就无法抓取到数据。
2. 由于上述两个控制面组件无法被发现，kube-prometheus 预置的控制面监控（控制面告警规则、Grafana 控制面看板）会处于"无数据"状态。

因此，在部署 kube-prometheus 之前，必须先调整 kubeadm 集群，把这些组件暴露给整个集群。

关于 kubelet 与 cAdvisor：在早期 Kubernetes 版本中，还需要为控制面与所有节点上的 kubelet 修改 cAdvisor 监控相关配置；由于 Kubernetes 的相应改动（见 kubernetes/kubernetes issue #56523），这一要求已不再需要，无需再做额外处理。

1.1 通过 kubeadm 配置文件在集群初始化前暴露控制面组件

官方推荐的修改方式是在kubeadm init时使用 kubeadm 配置文件。核心思路是在ClusterConfiguration中给controllerManager与scheduler追加extraArgs，把它们的bind-address从127.0.0.1改为0.0.0.0。

原文档给出了一份完整的示例配置（字段含义已补充）：

apiVersion: kubeadm.k8s.io/v1beta2 kind: ClusterConfiguration controlPlaneEndpoint: "192.168.1.173:6443" # 控制面对外暴露的稳定地址:端口 apiServer: extraArgs: authorization-mode: "Node,RBAC" # API Server 的鉴权模式，Node + RBAC 是推荐组合 controllerManager: extraArgs: bind-address: "0.0.0.0" # 关键：让 controller-manager 监听所有网卡 scheduler: extraArgs: bind-address: "0.0.0.0" # 关键：让 scheduler 监听所有网卡 certificatesDir: "/etc/kubernetes/pki" etcd: # one of local or external # 选择内嵌 etcd 或外部 etcd local: dataDir: "/var/lib/etcd" kubernetesVersion: "v1.23.1" # 按实际使用的 Kubernetes 版本填写 networking: dnsDomain: "cluster.local" # 集群 DNS 域名 serviceSubnet: "10.96.0.0/12" # Service 网段 imageRepository: "registry.k8s.io" # 镜像仓库

需要重点说明的参数：

• scheduler.extraArgs.bind-address与controllerManager.extraArgs.bind-address：这是本指南的核心。设置0.0.0.0后，两个组件将不再只回环地址上提供/metrics端点，而是对集群内所有地址可见，kube-prometheus 的 ServiceMonitor 才能发现并抓取指标。
• apiServer.extraArgs.authorization-mode：Node,RBAC是常见的推荐鉴权组合，与监控抓取时使用的 ServiceAccount 令牌（RBAC）相配合。

1.2 已存在的集群：直接修改静态 Pod 清单

如果你的 kubeadm 集群已经初始化完毕，不需要重建集群，只需在控制面节点上修改两个静态 Pod 清单，把--bind-address=127.0.0.1替换为--bind-address=0.0.0.0：

sed -e "s/- --bind-address=127.0.0.1/- --bind-address=0.0.0.0/" -i /etc/kubernetes/manifests/kube-controller-manager.yaml sed -e "s/- --bind-address=127.0.0.1/- --bind-address=0.0.0.0/" -i /etc/kubernetes/manifests/kube-scheduler.yaml

kubelet 会监听/etc/kubernetes/manifests目录并自动重建对应的静态 Pod，无需手动重启控制面组件。修改完成后，集群即满足 kube-prometheus 的控制面监控前提。

1.3 控制面组件以 Pod 形式存在时的服务选择器校验

原文档特别提醒：如果你的 Kubernetes 核心组件是以kube-system 命名空间中的 Pod形式运行的，请确保kube-prometheus-exporter-kube-scheduler与kube-prometheus-exporter-kube-controller-manager服务的spec.selector与这些 Pod 的标签一致，否则 ServiceMonitor 通过 Service 发现目标时会匹配不到 Pod。

从本仓库的控制面采集实现可以印证这一点。仓库把对控制面组件的发现定义为ServiceMonitor，通过标签选择器与命名空间约束来匹配服务与 Pod：

• kubernetesControlPlane-serviceMonitorKubeScheduler.yaml：selector.matchLabels为app.kubernetes.io/name: kube-scheduler，namespaceSelector.matchNames为kube-system。
• kubernetesControlPlane-serviceMonitorKubeControllerManager.yaml：selector.matchLabels为app.kubernetes.io/name: kube-controller-manager，命名空间同样限定在kube-system。

对应的 jsonnet 模板定义在 k8s-control-plane.libsonnet（serviceMonitorKubeScheduler）与 同文件 #L228-L279（serviceMonitorKubeControllerManager）。在serviceMonitorKubeScheduler中还可以看到两个抓取端点：默认每 30s 抓取一次https-metrics端口，另有一个每 5s 抓取/metrics/slis（SLO 相关指标）的端点，均使用bearerTokenFile挂载的 ServiceAccount 令牌做鉴权、tlsConfig.insecureSkipVerify: true处理自签名证书。

提示：本项目针对 kind 的 e2e 测试也使用了同样的 kubeadm 补丁思路。见 tests/e2e/kind/config.yml：通过kubeadmConfigPatches为controllerManager与scheduler设置extraArgs.bind-address: "0.0.0.0"。这说明"暴露控制面组件"是 kube-prometheus 在 kubeadm 系集群上可被正常监控的必要条件。

二、Metric Sources：kube-prometheus 监控哪些数据源

Kubernetes 集群组件本身就是用 Prometheus 指标埋点（instrumented）的，因此监控 Kubernetes 集群是 Prometheus 的自然选择——组件暴露指标后，只需让 Prometheus 完成服务发现，集群的大部分核心组件即可被覆盖。

除了各组件自带的指标，kube-prometheus 还引入两个补充数据源：

• kube-state-metrics：暴露的是"集群状态"而非单个组件的运行时指标，例如 Deployment、ReplicaSet、Pod 等对象的期望状态与实际状态、资源配额等元数据，是判断集群健康状态的关键数据源。
• node_exporter：用于监控集群节点的资源使用情况，包括 CPU、内存、磁盘利用率等，是节点级监控的基础。

完成本文的部署后，你将监控到以下内容：

• 集群状态：来自 kube-state-metrics
• 节点资源：来自 node_exporter
• kubelet
• apiserver
• kube-scheduler
• kube-controller-manager

从仓库的 jsonnet 源码结构看，这些数据源分别由components/目录下的组件模块生成：

• kube-state-metrics：kube-state-metrics.libsonnet
• node-exporter：node-exporter.libsonnet
• 控制面组件（apiserver / kube-scheduler / kube-controller-manager / kubelet / CoreDNS）：k8s-control-plane.libsonnet，其中serviceMonitorKubelet（同文件 #L108-L226）分别抓取/metrics（kubelet 自身指标）、/metrics/cadvisor（cAdvisor 容器指标）、/metrics/probes（探针指标）与/metrics/slis四个端点；apiserver 的 ServiceMonitor 则通过component: apiserver, provider: kubernetes标签在default命名空间发现 Kubernetes 内置的kubernetes服务（同文件 #L281-L357）。

这些 jsonnet 模板在编译后落地为 manifests 目录下可直接kubectl apply的 YAML 文件，例如 kubernetesControlPlane-serviceMonitorKubelet.yaml、kubernetesControlPlane-serviceMonitorApiserver.yaml、nodeExporter-serviceMonitor.yaml、kubeStateMetrics-serviceMonitor.yaml。

三、快速安装 kube-prometheus 监控栈

kube-prometheus 是一个"开箱即用"的监控方案集合：它把 Prometheus Operator、Prometheus、Alertmanager、node-exporter、kube-state-metrics、Grafana 以及配套的 Dashboard 与告警规则，统一打包成一组 manifests。本小节是快速安装流程，不深入讲解每个组件的原理。下文命令均可在当前仓库根目录执行。

3.1 克隆仓库并创建命名空间

git clone https://github.com/prometheus-operator/kube-prometheus cd kube-prometheus/

如果你已经在使用本仓库（例如通过镜像站点git clone https://gitcode.com/gh_mirrors/ku/kube-prometheus），可直接跳到创建命名空间步骤。

首先创建监控套件要运行的命名空间（可按需修改变量值）：

export NAMESPACE='monitoring' kubectl create namespace "$NAMESPACE"

仓库预置的命名空间定义位于 manifests/setup/namespace.yaml，其中带有pod-security.kubernetes.io/warn: privileged的 Pod Security 警告标签，表示该命名空间内特权工作负载只会收到警告而不会被拦截。

3.2 部署 Prometheus Operator

kubectl --namespace="$NAMESPACE" apply -f manifests/prometheus-operator

该命令创建 Prometheus Operator 的全部组件。注意：Custom Resource Definitions（CRD）在集群中就绪需要一小段时间，可通过下面的循环等待alertmanagers.monitoring.coreos.com这个 CRD 出现后再继续后续步骤：

until kubectl --namespace="$NAMESPACE" get alertmanagers.monitoring.coreos.com > /dev/null 2>&1; do sleep 1; printf "."; done

当前仓库的 Prometheus Operator 版本为0.94.1（见 jsonnet/kube-prometheus/versions.json）。对应的 Operator 部署文件位于 manifests/prometheusOperator-deployment.yaml，其需要的 RBAC（ClusterRole / ClusterRoleBinding / ServiceAccount）分别见 manifests/prometheusOperator-clusterRole.yaml 与 manifests/prometheusOperator-clusterRoleBinding.yaml。

关于时序：先创建 CRD 再创建 Operator，是为了避免 Operator 在 CRD 尚未注册时启动失败。也可以一次性应用manifests/setup中的 CRD（见 README Quickstart 的kubectl apply --server-side -f manifests/setup方式），本快速安装流程采用的是文档原始的按序部署方式。

3.3 部署 node-exporter 与 kube-state-metrics

kubectl --namespace="$NAMESPACE" apply -f manifests/node-exporter kubectl --namespace="$NAMESPACE" apply -f manifests/kube-state-metrics

• node-exporter 以 DaemonSet 形式在每个节点上运行（manifests/nodeExporter-daemonset.yaml），仓库当前版本为1.12.1。
• kube-state-metrics 以 Deployment 形式运行（manifests/kubeStateMetrics-deployment.yaml），仓库当前版本为2.20.0。

3.4 部署 Grafana 凭据与 Grafana 本体

先应用 Grafana 的凭据。默认用户名/密码为admin/admin，生产环境务必修改：

kubectl --namespace="$NAMESPACE" apply -f manifests/grafana/grafana-credentials.yaml

然后安装 Grafana 本身：

kubectl --namespace="$NAMESPACE" apply -f manifests/grafana

说明与补充：

• 在当前仓库中，Grafana 相关配置已经整合到 manifests/grafana-config.yaml、manifests/grafana-dashboardDefinitions.yaml、manifests/grafana-dashboardDatasources.yaml 等文件中；Grafana 当前版本为13.2.2（见 versions.json）。
• Grafana Deployment（manifests/grafana-deployment.yaml）通过env: []显式清空环境变量，把 Grafana 的管理员凭据交给挂载的凭据文件管理；数据源、Dashboard 则通过挂载到/etc/grafana/provisioning/datasources与/etc/grafana/provisioning/dashboards的 ConfigMap 进行 provisioning（见该文件中的 volumeMounts 与 dashboard 定义挂载）。
• 凭据文件位于 manifests/grafana-dashboardDatasources.yaml 周边的配套 Secret 中（quickstart 中的grafana-credentials.yaml对应本仓库 manifest 集合中的 Grafana Secret 资源）。Grafana 的默认访问方式与admin/admin登录说明可参考 docs/access-ui.md。

3.5 部署 Prometheus 本体及其 RBAC

先部署 Prometheus 应用本身（注意：roles 与 role-bindings 要单独用全局方式应用，因为它们作用于集群范围，不应受命名空间限定）：

find manifests/prometheus -type f ! -name prometheus-k8s-roles.yaml ! -name prometheus-k8s-role-bindings.yaml -exec kubectl --namespace "$NAMESPACE" apply -f {} \; kubectl apply -f manifests/prometheus/prometheus-k8s-roles.yaml kubectl apply -f manifests/prometheus/prometheus-k8s-role-bindings.yaml

命令要点：

• 第一条find ... -exec找出manifests/prometheus目录下除 roles 和 role-bindings 之外的所有文件，逐个在monitoring命名空间内应用，其中包含核心的 Prometheus CR 对象 manifests/prometheus-prometheus.yaml。
• 后两条不带--namespace参数，因为 ClusterRole 与 ClusterRoleBinding 是集群级资源。

Prometheus CR 关键字段（manifests/prometheus-prometheus.yaml）：

• replicas: 2：默认双副本高可用部署；
• alerting.alertmanagers：指向monitoring命名空间下的alertmanager-main服务；
• serviceAccountName: prometheus-k8s：抓取时使用该 ServiceAccount 的令牌做 kubelet / API 鉴权；
• securityContext.runAsNonRoot: true, runAsUser: 1000：以非 root 用户运行。

仓库当前 Prometheus 镜像版本为quay.io/prometheus/prometheus:v3.14.0。

3.6 部署 Alertmanager

kubectl --namespace="$NAMESPACE" apply -f manifests/alertmanager

Alertmanager 部署完成后，全套监控栈就绪。当前仓库中 Alertmanager 版本为0.34.1（见 versions.json）。其默认告警配置位于 manifests/alertmanager-secret.yaml，包含resolve_timeout: 5m、基于namespace/alertname的抑制规则（inhibit_rules）、以及Default/Watchdog/Critical/null四个接收器（receivers）——其中Watchdog接收器用于验证告警链路存活，null接收器用于丢弃InfoInhibitor类信息。

3.7 验证安装并访问三套 UI

所有 Pod 就绪后，即可通过以下 NodePort 访问 UI：

• Prometheus UI：节点端口30900
• Alertmanager UI：节点端口30903
• Grafana：节点端口30902

这些端口定义在 Service 清单中，可以通过修改 Service 定义来变更。仓库中对应的端口映射定义在 jsonnet 的 node-ports 扩展里（jsonnet/kube-prometheus/addons/node-ports.libsonnet）：Prometheus30900→9090、Alertmanager30903→9093、Grafana30902→3000。由于默认的 manifests/prometheus-service.yaml、manifests/alertmanager-service.yaml、manifests/grafana-service.yaml 均为 ClusterIP 类型，NodePort 由 examples/jsonnet-snippets/node-ports.jsonnet 引入的 node-ports mixin 在定制编译时生成。

如果不希望直接暴露 NodePort，推荐使用kubectl port-forward临时访问（详见 docs/access-ui.md）：

kubectl --namespace monitoring port-forward svc/prometheus-k8s 9090 kubectl --namespace monitoring port-forward svc/grafana 3000 kubectl --namespace monitoring port-forward svc/alertmanager-main 9093

更多关于如何将这三套服务暴露给集群外用户的方案，可参考仓库文档 docs/customizations/exposing-prometheus-alertmanager-grafana-ingress.md（Ingress 方式）与 docs/customizations/node-ports.md（NodePort mixin 使用方式）。

四、安装后的使用与验证建议

4.1 访问 Prometheus 验证控制面指标

kubeadm 集群完成上述安装后，进入 Prometheus UI 的 /targets 页面，应能看到以下 job 处于 UP 状态：

• kube-controller-manager：依赖前文第 1 节的bind-address调整，否则该 target 无法抓取；
• kube-scheduler：同样依赖前文配置；
• kubelet（含/metrics/cadvisor端点，抓取容器资源）；
• apiserver、kube-state-metrics、node-exporter等。

这些 job 名称的来源可见于 jsonnet 的_config.mixin._config（k8s-control-plane.libsonnet），例如kubeSchedulerSelector: 'job="kube-scheduler"'、kubeControllerManagerSelector: 'job="kube-controller-manager"'——告警规则与 Dashboard 正是通过这些 selector 与抓取 job 关联。

4.2 验证 Alertmanager 与告警规则

进入 Alertmanager UI 可查看当前接收到的告警。仓库预置了大量告警与录制规则，例如控制面告警保存在 manifests/kubernetesControlPlane-prometheusRule.yaml，Prometheus 自身告警在 manifests/prometheus-prometheusRule.yaml，节点与集群级告警来自 mixin（源码见 jsonnet/kube-prometheus/components/mixin/alerts 与 jsonnet/kube-prometheus/components/mixin/rules）。

4.3 验证 Grafana Dashboard

使用admin/admin（务必在生产环境修改）登录 Grafana 后，仓库已通过 provisioning 预置了多套 Dashboard，包括Kubernetes / API server、Kubernetes / Controller Manager、Kubernetes / Kubelet、Kubernetes / Nodes、Node Exporter、Cluster Total等（完整的 dashboard 定义见 manifests/grafana-dashboardDefinitions.yaml，对应的 volumeMount 挂载清单见 manifests/grafana-deployment.yaml）。若Kubernetes / Controller Manager看板无数据，请回到第 1 节检查bind-address配置是否生效。

五、常见问题排查速查

更多排查思路可参考 docs/troubleshooting.md。

结语

在 kubeadm 集群上启用 kube-prometheus 的关键一步，是让kube-controller-manager与kube-scheduler脱离127.0.0.1回环监听；完成这一步后，按本仓库 manifests 目录的顺序部署 Prometheus Operator、node-exporter、kube-state-metrics、Grafana、Prometheus 与 Alertmanager，即可在 NodePort30900/30902/30903上获得完整的集群监控体验。无论是通过 kubeadm 配置文件在初始化前预设，还是用sed修改已存在集群的静态 Pod 清单，其目的都是让 kube-prometheus 的 ServiceMonitor 能够发现并抓取控制面指标——这也是本文所述流程与仓库源码（k8s-control-plane.libsonnet、manifests）相互印证的底层逻辑。

• 云原生
• 可观测性
• 指标监控
• 监控大盘
• 告警