深入理解 Prometheus Operator:基于 Kubernetes 的 Prometheus 监控栈原生管理与 CRD 体系入门

原创2026-09-23 15:49:131,849 阅读
文章标签:云原生可观测性

深入理解 Prometheus Operator:基于 Kubernetes 的 Prometheus 监控栈原生管理与 CRD 体系入门

Prometheus Operator 是一个基于 Kubernetes Operator 模式的控制器,它以 Kubernetes 原生的方式部署与管理 Prometheus 及相关监控组件。本篇文章以官方 Introduction 文档为核心骨架,结合仓库内 Design、Installation 等文档与源码实现,系统讲解它的核心特性、十大自定义资源(CRD)分类、资源选择器机制以及三种主流安装方式。读完本文,你将掌握 Prometheus Operator 的整体架构心智模型,能够独立规划并落地一套 Kubernetes 原生监控栈。

Prometheus Operator 是什么

Prometheus Operator 是一个 Kubernetes Operator,它的核心职责是提供 Kubernetes 原生的 Prometheus 部署与管理能力。它不仅仅是把 Prometheus 打包成镜像运行,而是把"部署实例、生成抓取配置、下发告警与规则、维护高可用"这一整套生命周期管理动作全部封装进 Operator 控制器中,用户只需要声明式地描述"想要什么",剩下的交给 Operator 去调和(reconcile)实现。

从项目仓库结构可以看到,Prometheus Operator 的入口在 cmd/operator/main.go,它启动了若干个子控制器(prometheuscontroller、alertmanagercontroller、thanoscontroller、prometheusagentcontroller)以及 pkg/admission 中的准入校验 Webhook,分别负责不同资源的调和;所有 CRD 的类型定义集中在 pkg/apis/monitoring/v1 等目录下。

Prometheus Operator 提供的主要能力包括(但不限于):

  • Kubernetes 自定义资源(Custom Resources):使用 Kubernetes 自定义资源来部署和管理 Prometheus、Alertmanager 及相关组件;
  • 简化部署配置(Simplified Deployment Configuration):直接从原生 Kubernetes 资源中配置 Prometheus 的核心要素,例如版本、持久化、保留策略(retention)和副本数(replicas);
  • Prometheus 抓取目标配置(Target Configuration):基于熟悉的 Kubernetes 标签查询自动生成监控目标配置,无需学习 Prometheus 专属的配置语言。

核心概念:自定义资源(CRD)体系

Prometheus Operator 的核心设计思想是"一切皆 CRD"。它提供了一组 Custom Resource Definitions,让用户可以通过 kubectl 以声明式的方式配置 Prometheus 及相关实例。当前 Prometheus Operator 提供的 CRD 包括:

CRD 作用
Prometheus 部署和管理 Prometheus 服务端实例
Alertmanager 部署和管理 Alertmanager 告警处理实例
ThanosRuler 部署 Thanos Ruler,跨多套 Prometheus 执行记录与告警规则
ServiceMonitor 以 Service 为维度定义抓取目标
PodMonitor 以 Pod 为维度定义抓取目标
Probe 定义对 Ingress 与静态目标的探测(通常配合 blackbox exporter)
PrometheusRule 定义告警规则与记录规则
AlertmanagerConfig 定义 Alertmanager 的告警路由与抑制规则等子配置
PrometheusAgent 部署轻量级 Prometheus Agent(远程写入模式)
ScrapeConfig 以更底层的方式定义服务发现与抓取配置

上述 CRD 对应的完整 YAML 清单可以在 example/prometheus-operator-crd 与 example/prometheus-operator-crd-full 中找到;类型定义的权威出处则是 pkg/apis/monitoring/v1(v1)、pkg/apis/monitoring/v1alpha1 与 pkg/apis/monitoring/v1beta1。想要了解每个字段的具体含义,请参阅 API Reference。

为了帮助理解,官方文档建议先浏览 Design 页面获取所有资源的总体概览。下面我们把这十类资源分成两组来理解。

实例类资源(Instance-Based Resources):管理监控组件的生命周期

Prometheus Operator 实例类资源概览

实例类资源负责管理 Prometheus 生态系统中各组件的部署与生命周期。它们直接描述"我要跑一个什么样的监控组件",包括副本数、存储、镜像版本等运行时要素。

Prometheus

Prometheus CRD 在 Kubernetes 集群中部署一个 Prometheus 实例。它允许配置副本数、持久化存储以及用于发送告警的 Alertmanager。对于每个 Prometheus 资源,Operator 会在同一命名空间内部署 StatefulSet 对象(每个分片(shard)一个,默认分片数为 1)。

在 pkg/apis/monitoring/v1/prometheus_types.go 中可以看到,Prometheus 的 spec 通过 serviceMonitorSelector、podMonitorSelector、probeSelector、scrapeConfigSelector 等字段来决定纳入该实例的抓取配置资源(详见后文"资源选择器"一节)。值得注意的是,如果这四个 selector 字段全部为空(null),则 Prometheus 配置处于"非托管"状态——Operator 只会确保配置 Secret 存在,用户需要自行提供 gzip 压缩的 prometheus.yaml.gz;官方文档已将该行为标记为 deprecated,推荐改用 spec.additionalScrapeConfigs。

Alertmanager

Alertmanager CRD 在集群中部署一个 Alertmanager 实例,提供副本数和持久化存储的配置选项。每个 Alertmanager 资源对应同一命名空间下的一个 StatefulSet;当配置多个副本时,Operator 会以高可用模式运行这些实例,通过 gossip 协议在实例之间同步告警通知去重状态。

ThanosRuler

ThanosRuler CRD 在集群中部署一个 Thanos Ruler。

Prometheus Agent

PrometheusAgent CRD 在集群中部署一个 Prometheus Agent。

配置类资源(Config-Based Resources):定义"采什么、怎么采"

配置类资源关注的是集群内指标的采集与监控管理——它们定义指标如何被发现、收集和处理,而不负责部署监控组件本身。

Prometheus Operator 配置类资源概览

Prometheus 与 PrometheusAgent CRD 通过 podMonitorSelector、serviceMonitorSelector、probeSelector、scrapeConfigSelector 字段,决定哪些 ServiceMonitor、PodMonitor、Probe 与 ScrapeConfig 会被纳入对应实例的抓取配置。

ServiceMonitor:面向 Service 的抓取

ServiceMonitor CRD 定义如何监控一组动态的 Service。工作链路如下:Service 对象通过标签选择器发现 Pod,并将其纳入 EndpointSlice / Endpoints 对象;ServiceMonitor 再通过标签选择器发现这些 EndpointSlice / Endpoints 对象,并生成对应的 Prometheus 抓取配置。被监控的 Service 及其期望配置通过标签选择(label selections)来定义。

PodMonitor:面向 Pod 的抓取

PodMonitor CRD 定义如何监控一组动态的 Pod。它直接基于 Pod 标签发现目标并生成相应抓取配置,不要求先创建 Service 对象。相比 ServiceMonitor,它适合不需要 Service 抽象、直接以 Pod 为粒度抓取的场景。

Probe:面向 Ingress 与静态目标

Probe CRD 定义如何监控一组 Ingress 和静态目标。除了目标本身,Probe 对象还需要一个 prober——即负责探测目标并对外暴露指标供 Prometheus 抓取的服务,通常由 blackbox exporter 充当。

ScrapeConfig:更底层的抓取配置

ScrapeConfig CRD 允许你以接近原生 Prometheus 配置的方式定义服务发现与抓取规则。它的典型用途是抓取集群外部的目标,或构建 ServiceMonitor / Probe / PodMonitor 这些高层资源无法表达的抓取配置。Prometheus 与 PrometheusAgent 都有 scrapeConfigSelector 字段,需要设置为要匹配的标签列表。详细用法(包括 kubernetes_sd、static_config、file_sd、http_sd 等示例)请参阅 ScrapeConfig 开发指南。

AlertmanagerConfig:子配置与路由

AlertmanagerConfig CRD 允许配置集群中的 Alertmanager 实例。它描述 Alertmanager 配置的子部分,例如把告警路由到自定义 receiver、设置抑制(inhibition)规则等,然后由 Operator 合并进主配置。配置方式详见 Alerting 指南。

PrometheusRule:告警与记录规则

PrometheusRule CRD 允许定义告警规则和记录规则,供 Prometheus 或 Thanos Ruler 消费。规则由 Operator 调和后动态加载,无需重启 Prometheus 或 Thanos Ruler 即可生效。规则的实现与加载逻辑可在 pkg/operator/rules.go 中查看。

资源选择器(Resource Selectors):实例资源与配置资源如何建立关联

实例类资源通过一组 selector 字段来发现并关联配置类资源,这是理解 Prometheus Operator 数据流的关键。完整的 selector 列表如下:

  • serviceMonitorSelector / serviceMonitorNamespaceSelector:用于 Prometheus 与 PrometheusAgent CRD;
  • podMonitorSelector / podMonitorNamespaceSelector:用于 Prometheus 与 PrometheusAgent CRD;
  • probeSelector / probeNamespaceSelector:用于 Prometheus 与 PrometheusAgent CRD;
  • scrapeConfigSelector / scrapeConfigNamespaceSelector:用于 Prometheus 与 PrometheusAgent CRD;
  • ruleSelector / ruleNamespaceSelector:用于 Prometheus 与 ThanosRuler CRD;
  • alertmanagerConfigSelector / alertmanagerConfigNamespaceSelector:用于 Alertmanager CRD。

这些 selector 字段遵循标准的 Kubernetes 标签选择器语义,从 pkg/apis/monitoring/v1/prometheus_types.go 等源码的类型注释中可以确认如下规则:

  • 空选择器 {}:匹配所有对象;
  • 空值(字段未指定,null):对于资源选择器(resource selector),不匹配任何对象;对于命名空间选择器(namespace selector),只匹配当前命名空间;
  • 其他情况:按标签选择器匹配带有指定标签的对象。

以 ScrapeConfig 为例(示例来自 ScrapeConfig 开发指南):当未指定 scrapeConfigNamespaceSelector 时,只会选择与 Prometheus 资源同一命名空间下的 ScrapeConfig;若希望匹配所有命名空间,则显式设置为 scrapeConfigNamespaceSelector: {};若只想选择带有特定标签(如 environment: production)的命名空间,则使用 matchLabels 表达。同样的语义适用于 ServiceMonitor、PodMonitor、Probe 与 PrometheusRule。

部署 Prometheus Operator 的三种方式

安装前置条件

由于 CRD 中使用了 Common Expression Language (CEL) 做字段校验:

  • Prometheus Operator >= v0.84.0 要求 Kubernetes >= v1.25.0(或 >= v1.23.0 且开启 CustomResourceValidationExpressions feature gate);
  • v0.84.0 之前的版本要求 Kubernetes >= v1.16.0。

如果你是新手,官方强烈建议使用最新版本;如果集群较旧,建议先升级 Kubernetes 再升级 Prometheus Operator。各组件的版本兼容矩阵请参考 Compatibility 页面。

方式一:使用 YAML 文件安装(bundle.yaml)

第一步是安装 Operator 的 CRD,以及带有所需 RBAC 资源的 Operator 本身。在 default 命名空间部署:

LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name)
curl -sL https://github.com/prometheus-operator/prometheus-operator/releases/download/${LATEST}/bundle.yaml | kubectl create -f -

如果需要把 Operator 安装到非 default 命名空间,则需要借助 Kustomize:

NAMESPACE=my_namespace
TMPDIR=$(mktemp -d)
LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name)
curl -s "https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/refs/tags/$LATEST/kustomization.yaml" > "$TMPDIR/kustomization.yaml"
curl -s "https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/refs/tags/$LATEST/bundle.yaml" > "$TMPDIR/bundle.yaml"
(cd $TMPDIR && kustomize edit set namespace $NAMESPACE) && kubectl create -k "$TMPDIR"

Operator 启动可能需要几分钟,可用如下命令等待就绪:

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

仓库根目录的 bundle.yaml 就是这类聚合清单的本地示例,而 kustomization.yaml 则展示了如何对清单做 Kustomize 化定制。RBAC 相关清单可在 example/rbac/prometheus-operator 目录查看。

方式二:通过 Kube-Prometheus 安装

对于初学者,最省事的路径是直接部署 kube-prometheus——它会一并部署 Prometheus Operator,并且默认调度一个名为 prometheus-k8s 的 Prometheus,附带开箱即用的告警与规则。kube-prometheus 部署的是编译好的 Kubernetes manifests(位于其 manifests 目录)。

获取项目文件后,在项目根目录执行:

# 先创建命名空间和 CRD,等它们就绪后再创建其余资源,避免竞态
kubectl create -f manifests/setup

# 等待 "servicemonitors" CRD 创建完成(输出 "No resources found" 即表示成功)
until kubectl get servicemonitors --all-namespaces ; do date; sleep 1; echo ""; done

kubectl create -f manifests/

也可以把两个目录合并为单条命令一次性应用:

kubectl create -f manifests/setup -f manifests

但可能需要多次执行才能让所有组件成功创建。本文档所在仓库的 contrib/kube-prometheus/README.md 对 kube-prometheus 项目做了说明。

移除 kube-prometheus:当不再需要时,可以一键拆除:

kubectl delete --ignore-not-found=true -f manifests/ -f manifests/setup

方式三:使用 Helm Chart 安装

如果偏好 Helm,可以安装 Kube-Prometheus-Stack Helm Chart。它提供了一整套 Kubernetes manifests、Grafana 仪表盘和 Prometheus 规则,配合文档与脚本,可用 Prometheus + Prometheus Operator 快速构建端到端、易于运维的 Kubernetes 集群监控。需要注意:该 Chart 已不再属于 Prometheus-Operator 仓库,现由 Prometheus Community Helm Charts 维护。仓库内的 helm/README.md 可供参考。

快速上手:一个最小的可运行示例

结合 Developer Getting Started 指南,安装完成后即可体验"声明一个监控目标"的完整链路。完整示例文件位于 example/user-guides/getting-started。

首先部署一个暴露指标的应用(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

然后创建一个 ServiceMonitor,通过标签 app: example-app 选择上述 Service:

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

最后在 Prometheus 资源中通过 spec.serviceMonitorSelector 选中它:

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

这条链路完整展示了引言中强调的"用 Kubernetes 标签查询替代手写 Prometheus 配置":用户全程没有写过一行 Prometheus scrape 配置,抓取目标完全由标签选择器驱动,这正是 Prometheus Operator 配置抽象能力的直接体现。如果不想经过 Service 抽象,也可以改用 PodMonitor(基于 Pod 标签),示例见 example-app-pod-monitor.yaml。

下一步学习路径

现在你已经掌握了 Prometheus Operator 的基本图景。官方文档建议继续深入的方向包括:

  • 快速上手:参考 Getting Started 指南,实操 PodMonitor / ServiceMonitor;
  • API 参考:API Reference 提供各 CRD 所有字段的权威说明;
  • 平台指南:学习如何部署、配置与管理 Prometheus、Alertmanager、ThanosRuler 实例,见 Platform Guide;
  • 开发者指南:深入抓取、告警与记录规则的配置,见 Developer 目录 下的各篇指南;
  • 社区:了解如何参与 Prometheus Operator 社区贡献,见 CONTRIBUTING.md。

以 git clone 方式获取本仓库代码进行本地研究时,可直接使用项目地址。随着对 CRD 体系、资源选择器与调和循环的逐步深入,你将能够以完全声明式的方式,在 Kubernetes 上落地一套生产级、可扩展、易运维的 Prometheus 监控栈。

登录后查看全文
prometheus-operator