Prometheus Operator 完全指南:在 Kubernetes 上原生部署与管理 Prometheus 监控栈
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 一节):
- 自动化(Automation):通过 CRD 自动管理 Prometheus 监控目标,显著降低配置、实施和管理整套监控栈的工作量;
- 配置抽象与校验(Configuration Abstraction and Validation):用 Kubernetes Label Selector 替代手工编写 Prometheus relabeling 规则;同时由 Operator 承担
AlertmanagerConfig与PrometheusRule对象的配置校验复杂度; - 扩展性(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:每个
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) 专注于定义"指标如何被采集、处理和托管",而非管理组件部署:
- 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。
进阶阅读路径
- 全部 CRD 字段的权威参考:API Reference
- 架构与资源交互详解:设计文档
- 各组件安装与运维:平台指南、高可用、分片、Thanos 集成
- Agent 模式的来龙去脉:202201-prometheus-agent.md
- 变更记录与版本演进:CHANGELOG.md

