Generated by Answer me with HTML 0.6.1 · 2026-11-18 23:57 · ★ Star on GitHub
Prometheus Operator 深度解惑:CRD 联动原理与自定义监控实战
六大核心 CRD 外键关系、etcd 自定义监控全链路与 AlertmanagerConfig Bug 排雷
思维跃迁:为什么需要 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 集群生命周期 |
ServiceMonitorCRD 自动翻译生成prometheus.yml中的scrape_configs(告诉 Prometheus 去哪拉数据)。PrometheusRuleCRD 自动翻译生成prometheus.yml中的rule_files(告诉 Prometheus 什么时候报警)。
六大核心 CRD 联动原理(“数据库外键”心智模型)
可以把 etcd 中的每一种 CRD 看作一张独立的数据库表,它们之间完全通过 Label 标签选择器(相当于外键) 一环扣一环串联起来:
1. 所有常用 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 中!你可以通过两种方式查看真相:
# 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.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 的名称与端口名,告警链路天然畅通!
实战一:在 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。
# 在所有 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 均照此办理):
# 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
# 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 出图
- 部署上述 YAML 后,通过
kubectl -n kube-system get endpoints etcd-k8s确认 3 个地址均已挂载。 - 将
prometheus-k8s与grafanaService 改为NodePort暴露,打开 Prometheus 页面Status -> Targets,即可看到serviceMonitor/monitoring/etcd-k8s/0 (3/3 up)全部变绿! - 登录 Grafana,点击
Dashboards -> Import,输入官方 etcd 看板编号3070并关联 Prometheus 数据源,即可实时查看DB Size、Disk Sync Duration、Memory与Peer Traffic。
实战二:自定义报警规则 (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 集群法定半数故障告警规则
# 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 标签下可见!
双渠道通知方案对比与 AlertmanagerConfig Bug 深度排雷
当告警成功触发为 FIRING 后,在 kube-prometheus 中配置通知接收器有两条截然不同的路线:
路线 A(生产推荐):修改 alertmanager-main Secret 主配置
- 按前文规范编写包含钉钉 Webhook(指向已部署的
prometheus-webhook-dingtalkService)与 QQ/163 邮箱的配置文件myself.conf,子路由中务必开启"continue": true。 - 对配置执行
base64 -w0,删除旧alertmanager-mainSecret 后应用新的 Secret YAML(type: Opaque)。 - 通过解密
alertmanager-main-generatedSecret 或访问 Alertmanager 页面/#/status核对配置已生效。测试触发告警后,钉钉机器人群消息与 QQ 邮箱均能实时收到告警卡片!
路线 B(避坑排雷):AlertmanagerConfig CRD 的真实 Bug 剖析
理论上,Alertmanager CRD 支持通过 alertmanagerConfigSelector(如匹配标签 alertmanagerConfig: example)动态加载命名空间级别的 AlertmanagerConfig CRD 资源,实现配置与主 Secret 解耦(注意未配置 alertmanagerConfigNamespaceSelector 时默认只扫描同命名空间,且邮箱密码需引用提前建好的 Secret)。
然而在实际落地中,该方式在特定版本存在一个隐蔽 Bug,导致报警始终收不到:
- 隐式强制注入 Matcher:部署
AlertmanagerConfig后,解密查看alertmanager-main-generated会发现,Operator 在生成子路由时不仅写入了你定义的match: { mywarn: egon-critical },还强行自动塞入了一条matchers: [namespace="monitoring"]! - AND 逻辑冲突:旧版
match与新版matchers之间是 AND(同时满足) 关系!而你的PrometheusRule如果没有携带namespace="monitoring"标签,就永远无法命中该接收器。 - 版本语法弃用冲突:查看
prometheus-operatorPod 日志可见报错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-mainSecret 主配置) 是最稳妥的生产实践!