Generated by Answer me with HTML 0.6.1 · 2026-11-18 23:57 · ★ Star on GitHub

Prometheus Operator 深度解惑:CRD 联动原理与自定义监控实战

六大核心 CRD 外键关系、etcd 自定义监控全链路与 AlertmanagerConfig Bug 排雷

A

思维跃迁:为什么需要 Prometheus Operator?

很多同学初次接触 kube-prometheus 时最懵的地方在于:“以前改一个 prometheus.yml ConfigMap 就行了,现在突然冒出来十几个 YAML 和 CRD,反而找不到配置文件在哪了!”

对比两种管理范式,就能瞬间看清 Operator 的设计哲学:

对比维度 传统原生部署方式 Prometheus Operator 声明式方式
配置维护 手工编辑巨型 prometheus.yml 和 rules.yml ConfigMap,极易写错缩进 把监控目标与规则拆解为标准 K8s CRD(ServiceMonitor、PrometheusRule)
热更新方式 更新 ConfigMap 后需手工 curl -X POST /-/reload Operator 监听 CRD 变动,自动重新渲染配置并触发 Sidecar 无损重载
架构抽象 单纯的进程部署 用自定义控制器全自动托管 Prometheus、Alertmanager 与 Grafana 集群生命周期
核心映射公式(一秒看懂配置去向)
  • ServiceMonitor CRD ⟹ 自动翻译生成 prometheus.yml 中的 scrape_configs(告诉 Prometheus 去哪拉数据)。
  • PrometheusRule CRD ⟹ 自动翻译生成 prometheus.yml 中的 rule_files(告诉 Prometheus 什么时候报警)。
B

六大核心 CRD 联动原理(“数据库外键”心智模型)

可以把 etcd 中的每一种 CRD 看作一张独立的数据库表,它们之间完全通过 Label 标签选择器(相当于外键) 一环扣一环串联起来:

控制面配置驱动采集与告警声明层目标服务发现层serviceMonitorSelector 标签匹配ruleSelector 标签匹配selector.matchLabels + namespaceSelector定位真实 IP:Port 暴露点生成 rulefiles YAMLalertmanagerConfigSelector 标签匹配Prometheus CRD (k8s)ServiceMonitor CRDPrometheusRule CRDK8s Service (如etcd-k8s)Endpoints / Pod(/metrics)Prometheus Pod 规则目录Alertmanager CRD(main)AlertmanagerConfigCRD

1. 所有常用 CRD 家族职责速查

Prometheus Operator CRD 家族全览
  • Prometheus核心 CRD,声明 Prometheus Server 的副本数、存储、版本及各类 Selector
  • ServiceMonitor通过匹配 Service,将后端暴露 /metrics 的 Pod 或外部端点纳入采集目标
  • PodMonitor直接匹配 Pod 标签采集指标(无需通过 Service 中转)
  • Probe定义针对 Ingress 或外部 URL 的黑盒探测目标(需配合 Blackbox Exporter)
  • PrometheusRule声明告警规则(Alerting Rules)与预计算规则(Recording Rules)
  • Alertmanager核心 CRD,声明 Alertmanager 集群副本、版本与配置选择器
  • AlertmanagerConfig命名空间级别的告警路由与接收器 CRD(支持隔离租户配置)
  • ThanosRuler存在多个 Prometheus 实例时,统一跨集群管理计算规则

2. 深度揭秘:配置到底存哪了?Prometheus 如何发现 Alertmanager?

在 kube-prometheus 中,真实渲染出的最终配置文件并不在 ConfigMap 里,而是存放在 Secret 中!你可以通过两种方式查看真相:

bash
# 1. 进入 Prometheus 容器内部直接查看渲染生成的最终主配置与规则目录kubectl -n monitoring exec -ti prometheus-k8s-0 -- cat /etc/prometheus/config_out/prometheus.env.yamlkubectl -n monitoring exec -ti prometheus-k8s-0 -- ls /etc/prometheus/rules/prometheus-k8s-rulefiles-0/# 2. 解密查看 Alertmanager 最终生效的 gzip 压缩 Secret 配置(极有用排错神技!)kubectl get secret alertmanager-main-generated -n monitoring -o json \  | jq -r '.data."alertmanager.yaml.gz"' | base64 -d | gzip -d
Prometheus 自动对接 Alertmanager 的底层真相

查看 prometheus.env.yaml 可以发现,Operator 已经通过 kubernetes_sd_configs(role: endpoints, 监听 monitoring 命名空间)结合 relabel_configs 自动对接好了 Alertmanager:

  • 条件 1:__meta_kubernetes_service_name 正则匹配 alertmanager-main
  • 条件 2:__meta_kubernetes_endpoint_port_name 正则匹配 web(对应 9093 端口) 因此只要不破坏 alertmanager-main 这个 Service 的名称与端口名,告警链路天然畅通!
C

实战一:在 Operator 中自定义监控 etcd 集群(完整 4 步)

添加任意自定义监控项的核心口诀只有三句话:① 确认目标暴露 /metrics → ② 建 Service 关联目标 Endpoint → ③ 建 ServiceMonitor 选中该 Service。 无论被监控的 etcd 在 K8s 外部,还是作为 Static Pod 跑在 Master 内部,做法完全一致!

第 1 步:暴露 etcd 的 /metrics 接口(踩坑:127.0.0.1 拒连)

kubeadm 部署的 etcd 默认虽然在 2381 端口开启了指标,但仅绑定在 127.0.0.1 上,导致 Prometheus Pod 跨节点拉取时报错 connection refused。

bash
# 在所有 Master 节点修改 Static Pod 清单(改完等待几秒 Kubelet 自动重建,无需 apply)vim /etc/kubernetes/manifests/etcd.yaml# 将 --listen-metrics-urls=http://127.0.0.1:2381 修改为:--listen-metrics-urls=http://0.0.0.0:2381

第 2 步:创建无 Selector 的 Headless Service 与手动 Endpoints

因为 Static Pod 无法用常规 Service Selector 稳定选中,这里采用**“无 Selector Service + 同名同标签手动 Endpoints”**的通用万能桥接技巧(监控任何 K8s 外部中间件如外部 MySQL/Redis 均照此办理):

yaml
# etcd-svc.yaml:必须部署在与 Endpoints 相同的命名空间 (kube-system)apiVersion: v1kind: Servicemetadata:  name: etcd-k8s  namespace: kube-system  labels:    k8s-app: etcd              # 关键:该标签供后续 ServiceMonitor 筛选命中spec:  type: ClusterIP  clusterIP: None              # 关键:设为 None,该 Service 仅作监控挂载桥,不分配虚 IP  ports:  - name: port                 # 关键:端口名称需与 ServiceMonitor 中的 endpoints.port 一致    port: 2381---apiVersion: v1kind: Endpointsmetadata:  name: etcd-k8s               # 必须与上方 Service 名称严格一致  namespace: kube-system  labels:    k8s-app: etcd              # 标签也需与 Service 保持一致subsets:- addresses:  - ip: 192.168.71.101    nodeName: master01  - ip: 192.168.71.102    nodeName: master02  - ip: 192.168.71.103    nodeName: master03  ports:  - name: port    port: 2381

第 3 步:创建 ServiceMonitor 关联该 Service

yaml
# kubernetesControlPlane-serviceMonitorEtcd.yamlapiVersion: monitoring.coreos.com/v1kind: ServiceMonitormetadata:  name: etcd-k8s  namespace: monitoring        # ServiceMonitor 自身通常放在 monitoring 命名空间  labels:    k8s-app: etcd-k8sspec:  jobLabel: k8s-app  endpoints:  - port: port                 # 对应 Service 中定义的 ports[].name    interval: 15s  selector:    matchLabels:      k8s-app: etcd            # 精准匹配刚才创建的 etcd-k8s Service  namespaceSelector:    matchNames:    - kube-system              # 声明目标 Service 所在的跨命名空间位置

第 4 步:验证 Target 上线并配置 Grafana 出图

  1. 部署上述 YAML 后,通过 kubectl -n kube-system get endpoints etcd-k8s 确认 3 个地址均已挂载。
  2. 将 prometheus-k8s 与 grafana Service 改为 NodePort 暴露,打开 Prometheus 页面 Status -> Targets,即可看到 serviceMonitor/monitoring/etcd-k8s/0 (3/3 up) 全部变绿!
  3. 登录 Grafana,点击 Dashboards -> Import,输入官方 etcd 看板编号 3070 并关联 Prometheus 数据源,即可实时查看 DB Size、Disk Sync Duration、Memory 与 Peer Traffic。
D

实战二:自定义报警规则 (PrometheusRule) 与触发测试

1. ruleSelector 规则匹配原理

执行 kubectl -n monitoring get prometheus k8s -o yaml 查看其 spec.ruleSelector:

  • 若配置为 ruleSelector: {}(默认配置):代表匹配所有 PrometheusRule 对象,创建规则时无需添加特殊标签;
  • 若配置为 matchLabels: { prometheus: k8s, role: alert-rules }:则你创建的每个 PrometheusRule 必须严格携带这两个标签,否则会被 Operator 忽略!

2. 编写 etcd 集群法定半数故障告警规则

yaml
# prometheus-etcdRules.yamlapiVersion: monitoring.coreos.com/v1kind: PrometheusRulemetadata:  name: etcd-rules  namespace: monitoringspec:  groups:  - name: etcd    rules:    - alert: EtcdClusterUnavailable      annotations:        summary: etcd cluster small        description: If one more etcd peer goes down the cluster will be unavailable      expr: |        # 当挂掉的 etcd 实例数 (up==0) 超过总数一半向上取整时触发告警        # 测试技巧:可临时改为 count(up{job="etcd"}) > 1 刻意触发,用于联调下游通知!        count(up{job="etcd"} == 0) > ceil(count(up{job="etcd"}) / 2)      for: 1m      labels:        mywarn: egon-critical  # 使用独有标签避开内置默认路由截胡

部署后,Operator 会自动在 Prometheus 容器 /etc/prometheus/rules/prometheus-k8s-rulefiles-0/ 目录下生成名为 monitoring-etcd-rules-<uuid>.yaml 的规则文件,并在 Web 页面 Alerts 标签下可见!

E

双渠道通知方案对比与 AlertmanagerConfig Bug 深度排雷

当告警成功触发为 FIRING 后,在 kube-prometheus 中配置通知接收器有两条截然不同的路线:

稳定可靠 (推荐)存在版本兼容性 Bug 隐患双通道成功送达导致条件冲突失灵告警在 Prometheus 转为Firing发送至Alertmanager-main选择配置路线?路线 A: 修改alertmanager-mainSecret 主配置路线 B: 创建AlertmanagerConfigCRD同时路由至钉钉 Webhook与 QQ 邮箱Operator 自动强行追加namespace="monitoring"匹配

路线 A(生产推荐):修改 alertmanager-main Secret 主配置

  1. 按前文规范编写包含钉钉 Webhook(指向已部署的 prometheus-webhook-dingtalk Service)与 QQ/163 邮箱的配置文件 myself.conf,子路由中务必开启 "continue": true。
  2. 对配置执行 base64 -w0,删除旧 alertmanager-main Secret 后应用新的 Secret YAML(type: Opaque)。
  3. 通过解密 alertmanager-main-generated Secret 或访问 Alertmanager 页面 /#/status 核对配置已生效。测试触发告警后,钉钉机器人群消息与 QQ 邮箱均能实时收到告警卡片!

路线 B(避坑排雷):AlertmanagerConfig CRD 的真实 Bug 剖析

理论上,Alertmanager CRD 支持通过 alertmanagerConfigSelector(如匹配标签 alertmanagerConfig: example)动态加载命名空间级别的 AlertmanagerConfig CRD 资源,实现配置与主 Secret 解耦(注意未配置 alertmanagerConfigNamespaceSelector 时默认只扫描同命名空间,且邮箱密码需引用提前建好的 Secret)。

然而在实际落地中,该方式在特定版本存在一个隐蔽 Bug,导致报警始终收不到:

Bug 根因实录:为什么配了 AlertmanagerConfig 却收不到邮件?
  1. 隐式强制注入 Matcher:部署 AlertmanagerConfig 后,解密查看 alertmanager-main-generated 会发现,Operator 在生成子路由时不仅写入了你定义的 match: { mywarn: egon-critical },还强行自动塞入了一条 matchers: [namespace="monitoring"]!
  2. AND 逻辑冲突:旧版 match 与新版 matchers 之间是 AND(同时满足) 关系!而你的 PrometheusRule 如果没有携带 namespace="monitoring" 标签,就永远无法命中该接收器。
  3. 版本语法弃用冲突:查看 prometheus-operator Pod 日志可见报错 msg="'matchers' field is using a deprecated syntax which will be removed in future versions"——即便后续在 PrometheusRule 中强行补加了 namespace: monitoring 标签且网页显示 FIRING,受此版本混合渲染 Bug 影响,邮件依然可能无法触发。
  • 排障结论:遇到此现象时,务必查看 prometheus-operator 日志并解密 alertmanager-main-generated,直接切换回 路线 A(维护 alertmanager-main Secret 主配置) 是最稳妥的生产实践!