Prometheus Operator 完全指南:在 Kubernetes 上原生部署与管理 Prometheus 监控栈

原创2026-09-23 13:39:271,658 阅读
文章标签:云原生可观测性

Prometheus Operator 完全指南:在 Kubernetes 上原生部署与管理 Prometheus 监控栈

导读

Prometheus Operator 是一个基于 Kubernetes Operator 模式的控制器,它用 Kubernetes 自定义资源(CRD)来声明式地部署、配置和管理 Prometheus、Alertmanager、Thanos Ruler 等监控组件,让"监控栈即代码"成为现实。读完本文,你将掌握 Prometheus Operator 的核心架构与全部 10 个 CRD 的用途、API 版本稳定性策略、三种安装方式(bundle.yaml / kube-prometheus / Helm Chart)、快速启动与彻底卸载的完整命令,以及如何用 ServiceMonitor/PodMonitor 自动生成抓取配置的实战方法。

项目概览:为什么要用 Operator 管理监控

Prometheus Operator 为 Kubernetes 提供原生(Kubernetes native)的 Prometheus 及周边监控组件的部署和管理能力。项目定位非常明确:简化并自动化基于 Prometheus 的 Kubernetes 集群监控栈的配置。

其核心能力包括(源自 README.md 与 Documentation/getting-started/introduction.md):

  • Kubernetes 自定义资源:使用 Kubernetes 自定义资源部署和管理 Prometheus、Alertmanager 及相关组件,监控配置从 YAML 变为一等公民;
  • 简化部署配置:通过一个原生 Kubernetes 资源即可配置 Prometheus 的版本、持久化、保留策略(retention)、副本数(replicas)等基础项;
  • Prometheus 目标配置自动化:基于熟悉的 Kubernetes 标签查询(label queries)自动生成监控目标配置,无需学习 Prometheus 专属配置语言。

项目的目标可以归纳为三个关键词(见 introduction 文档的 Goals 一节):

  1. 自动化(Automation):通过 CRD 自动管理 Prometheus 监控目标,显著降低配置、实施和管理整套监控栈的工作量;
  2. 配置抽象与校验(Configuration Abstraction and Validation):用 Kubernetes Label Selector 替代手工编写 Prometheus relabeling 规则;同时由 Operator 承担 AlertmanagerConfig 与 PrometheusRule 对象的配置校验复杂度;
  3. 扩展性(Scaling):提供 ThanosRuler 进行规则评估、抓取目标分片(scrape target sharding)跨多实例负载分发、以及通过 Thanos sidecar 对接长期存储等能力。

项目状态与 CRD API 版本稳定性

Operator 本身被认为是生产就绪(production ready)的。但不同 CRD 的 API 版本稳定性不同,README.md 明确给出了以下分级策略:

API 版本 状态 使用建议
monitoring.coreos.com/v1 stable(稳定) 变更以向后兼容方式进行,可放心用于生产
monitoring.coreos.com/v1beta1 unstable(不稳定) 变更可能发生,但团队尽量避免;接受破坏性变更风险的用户可生产使用
monitoring.coreos.com/v1alpha1 unstable(不稳定) 变更频繁,建议避免在关键(mission-critical)环境中使用

从源码看,v1 版本的资源注册在 pkg/apis/monitoring/v1/register.go,其中 addKnownTypes 注册了 Prometheus、ServiceMonitor、PodMonitor、Probe、Alertmanager、PrometheusRule、ThanosRuler 等对象;而 PrometheusAgent、ScrapeConfig 等较新资源位于 v1alpha1(见 pkg/apis/monitoring/v1alpha1 目录)。这种版本分层正是为了给新特性提供快速迭代空间,同时保护稳定 API 的兼容性承诺。

核心机制:Operator 监控 API Server 并保持配置同步

Prometheus Operator 的核心工作方式是:监听 Kubernetes API Server 上特定对象的变更,并确保当前 Prometheus 部署与这些对象保持一致(Reconcile 循环)。它针对以下 CustomResourceDefinition(CRD)工作:

  • Prometheus:定义期望的 Prometheus 部署;
  • PrometheusAgent:定义期望的 Prometheus 部署,但运行在 Agent 模式;
  • Alertmanager:定义期望的 Alertmanager 部署;
  • ThanosRuler:定义期望的 Thanos Ruler 部署;
  • ServiceMonitor:声明式指定一组 Kubernetes Service 应如何被监控,Operator 根据 API Server 中对象的当前状态自动生成 Prometheus 抓取配置;
  • PodMonitor:声明式指定一组 Pod 应如何被监控,同样自动生成抓取配置;
  • Probe:声明式指定一组 Ingress 或静态目标应如何被监控;
  • ScrapeConfig:声明式指定要添加到 Prometheus 的抓取配置,特别适合抓取 Kubernetes 集群外部的资源;
  • PrometheusRule:定义一组期望的 Prometheus 告警/记录规则,Operator 生成规则文件供 Prometheus 实例使用;
  • AlertmanagerConfig:声明式指定 Alertmanager 配置的子部分,支持将告警路由到自定义接收器(receiver)以及设置抑制规则(inhibit rules)。

Operator 会自动检测上述任一对象在 API Server 中的变化,并确保匹配的部署和配置保持同步。

实例型资源与配置型资源

设计文档 将这 10 个 CRD 划分为两大类,这对理解架构至关重要:

实例型资源(Instance-Based Resources) 负责管理 Prometheus 生态中各组件实例的部署与生命周期:

Prometheus Operator 实例型资源关系图

  • Prometheus:每个 Prometheus 资源会在同命名空间下由 Operator 部署 StatefulSet(每个分片一个,默认分片数为 1),可配置副本、持久化存储、以及用于发送告警的 Alertmanager;
  • Alertmanager:每个 Alertmanager 资源部署一个 StatefulSet,可配置副本数与持久化存储;多副本时 Operator 以高可用模式运行;
  • ThanosRuler:支持跨多个 Prometheus 实例处理记录/告警规则,至少需要一个连接 Thanos Querier 或 Prometheus 实例的 query endpoint;
  • PrometheusAgent:与 Prometheus 类似但运行在 Agent 模式,裁剪掉了告警、PrometheusRule 选择器、remote-read、存储和 Thanos sidecar 等配置(背景见 202201-prometheus-agent.md)。

配置型资源(Config-Based Resources) 专注于定义"指标如何被采集、处理和托管",而非管理组件部署:

Prometheus Operator 配置型资源与实例型资源的关系图

  • ServiceMonitor:通过 label selector 选择 Service 对象,进而发现 EndpointSlice/Endpoints 中的 Pod 并配置 Prometheus 采集;
  • PodMonitor:直接基于 Pod 标签发现目标,无需经过 Service;
  • Probe:监控 Ingress 与静态目标,需要一个 prober(如 blackbox exporter)来探测目标并提供指标;
  • ScrapeConfig:用于抓取集群外目标或创建 ServiceMonitor/Probe/PodMonitor 无法表达的高阶抓取配置;
  • AlertmanagerConfig:配置 Alertmanager 的路由子段与抑制规则;
  • PrometheusRule:定义供 Prometheus 或 Thanos Ruler 消费的告警/记录规则,由 Operator 调和并动态加载,无需重启 Prometheus。

资源选择器(Resource Selectors):实例与配置的关联机制

实例型资源通过选择器字段发现并关联配置型资源(见 design.md):

  • serviceMonitorSelector / serviceMonitorNamespaceSelector(Prometheus、PrometheusAgent)
  • podMonitorSelector / podMonitorNamespaceSelector(Prometheus、PrometheusAgent)
  • probeSelector / probeNamespaceSelector(Prometheus、PrometheusAgent)
  • scrapeConfigSelector / scrapeConfigNamespaceSelector(Prometheus、PrometheusAgent)
  • ruleSelector / ruleNamespaceSelector(Prometheus、ThanosRuler)
  • alertmanagerConfigSelector / alertmanagerConfigNamespaceSelector(Alertmanager)

选择器遵循标准 Kubernetes 标签选择器语义:空选择器 {} 匹配所有对象;null 选择器(未指定字段)对资源选择器匹配不到任何对象、对命名空间选择器仅匹配当前命名空间;否则按指定标签匹配。更完整的示例见 ScrapeConfig 文档。

动态准入控制:启动前拦截非法规则

为了防止非法的 Prometheus 告警/记录规则导致已部署的 Prometheus 实例故障,项目提供了一个准入 webhook,在 PrometheusRule 资源创建或更新时对其进行校验。

从实现看,准入逻辑位于 pkg/admission/admission.go,在 Operator 启动时注册到 HTTP 服务上(见 cmd/operator/main.go),与 /metrics、/healthz、pprof 等端点共用同一个 Web Server。这意味着规则校验发生在资源真正写入集群之前,能有效避免"坏规则上线导致 Prometheus 拒载配置"的连锁故障。

Prometheus Operator vs kube-prometheus vs 社区 Helm Chart

README 特意澄清了三者关系,这也是新手最容易混淆的地方:

  • Prometheus Operator:使用 Kubernetes 自定义资源简化 Prometheus、Alertmanager 及周边监控组件的部署与配置,是本文主体;
  • kube-prometheus:基于 Prometheus Operator 的完整集群监控栈示例配置集,包含多个 Prometheus/Alertmanager 实例、node_exporter 等指标导出器、抓取目标配置以及示例告警规则。相关说明可参考仓库中的 contrib/kube-prometheus/README.md;
  • 社区 Helm Chart(kube-prometheus-stack):由 Prometheus 社区维护的 prometheus-community/kube-prometheus-stack,提供与 kube-prometheus 类似的功能集,不再隶属于 prometheus-operator 仓库。

三者的定位是"核心引擎 / 开箱即用栈 / 打包分发方式"的关系:kube-prometheus 与 Helm Chart 都构建在 Prometheus Operator 之上。

安装前置条件与兼容性

README 指出 Operator 至少要求 Kubernetes 1.16.0。安装文档 补充了更细的版本约束:

  • >= v0.84.0 的版本:由于 CRD 中使用了 Common Expression Language(CEL),要求 Kubernetes >= v1.25.0(或在开启 CustomResourceValidationExpressions 特性门控时 >= v1.23.0);
  • v0.84.0 之前的版本:要求 Kubernetes >= v1.16.0。

兼容性文档 还给出组件兼容矩阵要点:Operator 支持 Prometheus >= v2.0.0(e2e 测试主要针对 v3.14.0),兼容 Alertmanager v0.15 及以上(e2e 主要针对 v0.34.0),兼容 Thanos v0.10 及以上(e2e 主要针对 v0.42.4)。刚上手时,强烈建议使用最新稳定版本;如果集群与 Operator 版本都较旧,官方建议先升级 Kubernetes,再升级 Operator。

快速开始:三种安装方式

方式一:bundle.yaml(单命令部署,推荐快速体验)

注意:这个快速开始不会部署整套监控栈。如果需要完整监控栈,请使用 kube-prometheus;如果已经应用过 bundle.yaml 又想改用完整栈,先执行 kubectl delete -f bundle.yaml 删除 bundle。

选择某个 release 后,在 default 命名空间部署 Operator:

kubectl create -f bundle.yaml

bundle.yaml 位于仓库根目录,是包含 CRD、RBAC、Deployment 等全部资源的聚合清单(该文件由 scripts/generate-bundle.sh 生成,仓库根目录的 kustomization.yaml 是其 kustomize 基础)。

若要部署到其他命名空间,需要 kustomize 工具:

NAMESPACE=my_namespace kustomize edit set namespace $NAMESPACE && kubectl create -k .

注意:部署到非 default 命名空间时,务必同步修改 ClusterRoleBinding 中的命名空间。

等待 Operator 就绪:

kubectl wait --for=condition=Ready pods -l app.kubernetes.io/name=prometheus-operator

方式二:kube-prometheus(整套监控栈)

kube-prometheus 部署 Prometheus Operator 的同时,会默认调度一个名为 prometheus-k8s 的 Prometheus 并附带告警与规则:

git clone https://github.com/prometheus-operator/kube-prometheus.git
cd kube-prometheus
kubectl create -f manifests/setup
until kubectl get servicemonitors --all-namespaces ; do date; sleep 1; echo ""; done
kubectl create -f manifests/

先创建命名空间与 CRD 是为了避免部署监控组件时的竞态条件;两个目录也可以一次性应用(kubectl create -f manifests/setup -f manifests),但可能需要多次执行才能全部创建成功。清理时执行 kubectl delete --ignore-not-found=true -f manifests/ -f manifests/setup。

方式三:Helm Chart

安装 Kube-Prometheus-Stack 即可获得一套包含 Kubernetes 清单、Grafana 仪表盘和 Prometheus 规则的端到端集群监控方案。该 Chart 目前由 Prometheus 社区独立维护。

集群外运行(开发调试)

在本地运行 Operator(需要 kubectl 可访问目标集群):

make
scripts/run-external.sh <kubectl cluster name>

make 会先构建二进制(见 Makefile),随后 scripts/run-external.sh 以集群外模式拉起 Operator。源码层面,Operator 的入口在 cmd/operator/main.go,它支持三个子命令:start(运行 Operator,默认)、crds(将内嵌 CRD 以 YAML 输出到 stdout)、full-crds(输出含全部字段的完整 CRD)。

Operator 启动时的能力探测

从 cmd/operator/main.go 可以看到,Operator 启动时会通过 checkPrerequisites 逐一探测集群能力(对应源码第 69-101 行):检查各 CRD 是否安装、Operator 的 ServiceAccount 是否具备对应权限(get/list/watch 及 status 子资源 update),并据此决定是否启用 Prometheus、PrometheusAgent、Alertmanager、ThanosRuler 控制器;还会检测 EndpointSlice(K8s >= v1.21)、Pod Topology Labels(K8s >= v1.35)、StorageClass 读取等能力,以及大量运维参数(命名空间白/黑名单、--prometheus-config-reloader 镜像、--controller-id、--repair-policy-for-statefulsets 等)。这种"按能力自适应"的设计使得同一个 Operator 二进制可以平滑运行在多种 Kubernetes 版本上。

实战:用 ServiceMonitor 与 PodMonitor 自动生成抓取配置

下面演示 README 所述"自动生成监控目标配置"的最小闭环,完整示例 YAML 均可在 example/user-guides/getting-started 目录中找到,也可参考 开发者入门指南。

第 1 步:部署示例应用(3 副本,暴露 8080 端口的指标):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-app
  template:
    metadata:
      labels:
        app: example-app
    spec:
      containers:
      - name: example-app
        image: quay.io/brancz/prometheus-example-app:v0.5.0
        ports:
        - name: web
          containerPort: 8080

第 2 步:用 Service 暴露应用(选中标签 app: example-app 的 Pod):

kind: Service
apiVersion: v1
metadata:
  name: example-app
  labels:
    app: example-app
spec:
  selector:
    app: example-app
  ports:
  - name: web
    port: 8080

第 3 步:创建 ServiceMonitor——通过标签 app: example-app 选中 Service,并额外打上 team: frontend 标签用于后续选择器匹配:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: example-app
  labels:
    team: frontend
spec:
  selector:
    matchLabels:
      app: example-app
  endpoints:
  - port: web

第 4 步:在 Prometheus 资源中指定选择器,让 Operator 把匹配的 ServiceMonitor 纳入抓取配置:

apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: prometheus
spec:
  serviceAccountName: prometheus
  serviceMonitorSelector:
    matchLabels:
      team: frontend

如果应用没有 Service,可直接使用 PodMonitor 按 Pod 标签抓取:

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: example-app
  labels:
    team: frontend
spec:
  selector:
    matchLabels:
      app: example-app
  podMetricsEndpoints:
  - port: web

对应在 Prometheus 中使用 spec.podMonitorSelector 选择。整个过程无需手写任何 Prometheus 抓取配置——Operator 会读取 ServiceMonitor/PodMonitor 资源并自动生成 Prometheus 配置文件,再通过 config-reloader 动态加载。相关类型定义(如 ServiceMonitorSpec 的 selector/endpoints 语义)可在 pkg/apis/monitoring/v1/servicemonitor_types.go 与 pkg/apis/monitoring/v1/podmonitor_types.go 中查阅。

彻底卸载 Prometheus Operator

第 1 步:删除所有命名空间中的自定义资源。Operator 会自动关停并移除 Prometheus、Alertmanager Pod 及关联的 ConfigMap:

for n in $(kubectl get namespaces -o jsonpath={..metadata.name}); do
  kubectl delete --all --namespace=$n prometheus,servicemonitor,podmonitor,alertmanager
done

第 2 步:几分钟后删除 Operator 本身:

kubectl delete -f bundle.yaml

第 3 步:清理 Operator 自动创建的 Service 与 CRD。Operator 会在每个创建了 Prometheus/Alertmanager 资源的命名空间自动创建 prometheus-operated 与 alertmanager-operated 服务,并定义若干 CRD:

for n in $(kubectl get namespaces -o jsonpath={..metadata.name}); do
  kubectl delete --ignore-not-found --namespace=$n service prometheus-operated alertmanager-operated
done

kubectl delete --ignore-not-found customresourcedefinitions \
  prometheuses.monitoring.coreos.com \
  servicemonitors.monitoring.coreos.com \
  podmonitors.monitoring.coreos.com \
  alertmanagers.monitoring.coreos.com \
  prometheusrules.monitoring.coreos.com \
  alertmanagerconfigs.monitoring.coreos.com \
  scrapeconfigs.monitoring.coreos.com

CRD 清单的权威副本位于 example/prometheus-operator-crd 与 example/prometheus-operator-crd-full,可直接对照查看每个 CRD 的完整字段。

测试、贡献与故障排查

  • 测试:参见 TESTING.md,e2e 测试位于 test/e2e,覆盖 Alertmanager、Prometheus、PrometheusAgent、ThanosRuler、规则、抓取配置、拓扑分片等场景;
  • 贡献:参见 CONTRIBUTING.md,其中包含 AI 使用政策(AI Use Policy)——项目允许贡献者在遵守该政策的前提下使用 AI 工具参与开发;
  • 安全:发现未公开披露的安全漏洞时,不要通过 issue 上报,请直接联系 MAINTAINERS.md 中列出的维护者邮箱;来自自动化安全扫描器的报告请参照 Prometheus 官方安全文档流程处理;
  • 故障排查:常见问题与 FAQ 汇总在 troubleshooting.md。

进阶阅读路径

登录后查看全文
prometheus-operator