📚 课程目录第4章 ServiceMonitor与PodMonitor配置

4. ServiceMonitor 与 PodMonitor 配置：标签匹配规则、命名空间选择、端口与路径配置错误排查

在 Prometheus Operator 体系中，ServiceMonitor 和 PodMonitor 是定义抓取目标的核心 CRD（Custom Resource Definition）。误差预算台账数据不准，往往源于这两类资源的配置与目标服务实际状态之间存在偏差。本章聚焦于标签匹配、命名空间作用域、端口与路径三个最容易出错的维度，结合排查方法进行系统梳理。

4.1 标签匹配规则：选择器与 relabel 的协同

ServiceMonitor 通过 selector 字段匹配 Service 的标签，进而发现后端 Pod 的抓取端点。PodMonitor 则直接通过 selector 匹配 Pod 的标签。两者都支持 matchLabels 和 matchExpressions 两种匹配模式。

匹配方式	语法示例	匹配逻辑	常见错误
`matchLabels`	`app: nginx`	所有指定标签键值对必须完全匹配（AND 逻辑）	标签值拼写错误、大小写敏感、遗漏必要标签
`matchExpressions`	`{key: env, operator: In, values: [prod, staging]}`	支持 In、NotIn、Exists、DoesNotExist 等操作符	操作符使用错误、values 列表为空或格式错误

排查要点：使用 kubectl get servicemonitor <name> -o yaml 或 kubectl get podmonitor <name> -o yaml 查看实际配置。对比目标 Service/Pod 的标签，确认选择器是否命中。Prometheus Operator 的日志中会输出 no matching service found 或 no matching pods found 等提示，这是最直接的排查入口。

除了选择器匹配，relabel_configs 是标签处理的另一关键环节。ServiceMonitor 和 PodMonitor 中的 relabel 规则在抓取前执行，用于动态修改或过滤目标标签。常见的错误包括：

标签覆盖导致目标丢失：使用 replacement 或 targetLabel 时，意外覆盖了 __address__ 或 __metrics_path__ 等内部标签。
keep/drop 规则过于严格：正则表达式写错或条件判断不当，过滤掉了本应保留的目标。
标签映射错误：将源标签映射到不存在的目标标签，导致后续抓取无法识别。

调试技巧：在 Prometheus UI 的 Status → Targets 页面查看目标状态。如果目标显示为 0 up / 0 down，说明选择器未匹配到任何端点。使用 promtool debug 或直接查看 Prometheus 的 /api/v1/targets API 可以获取更详细的标签处理结果。

4.2 命名空间选择：作用域与跨命名空间抓取

ServiceMonitor 和 PodMonitor 的 namespaceSelector 字段决定了它们可以匹配哪些命名空间中的资源。配置不当会导致目标完全不可见。

namespaceSelector 的三种模式：

any: true — 匹配所有命名空间中的资源。适用于全局监控场景，但需注意权限控制。
matchNames: [ns1, ns2] — 仅匹配指定命名空间列表中的资源。最常用，需确保列表完整。
不设置（默认） — 仅匹配 ServiceMonitor/PodMonitor 自身所在的命名空间。容易遗漏跨命名空间的服务。

以下是一个典型的跨命名空间配置错误案例：

# 错误配置：ServiceMonitor 在 monitoring 命名空间，但未指定 namespaceSelector
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-app
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: my-app
  endpoints:
  - port: metrics
  # 缺少 namespaceSelector，默认只匹配 monitoring 命名空间中的 Service
  # 而目标 Service 在 production 命名空间，导致抓取不到

# 正确配置：显式指定目标命名空间
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-app
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: my-app
  namespaceSelector:
    matchNames:
    - production
  endpoints:
  - port: metrics

排查命令：使用

kubectl get servicemonitor -A -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.metadata.name}{"\t"}{.spec.namespaceSelector}{"\n"}{end}'

快速查看所有 ServiceMonitor 的命名空间选择配置。对比目标 Service 所在的命名空间，确认是否在匹配范围内。

4.3 端口与路径配置：抓取端点的最终定位

在 ServiceMonitor 的 endpoints 字段中，port 或 targetPort 指定了抓取端口，path 指定了 HTTP 路径。PodMonitor 类似，但直接引用 Pod 的容器端口名称或端口号。配置错误会导致 Prometheus 无法建立连接或收到非预期的响应。

配置项	说明	常见错误	排查方法
`port`	引用 Service 或 Pod 中定义的端口名称	端口名称拼写错误、Service 中未定义该名称	`kubectl get svc <name> -o yaml` 检查 ports 列表
`targetPort`	直接指定端口号，绕过端口名称引用	端口号与容器监听端口不一致、Pod 未暴露该端口	`kubectl get pod -o yaml` 检查容器 ports 配置
`path`	Metrics 端点 HTTP 路径，默认为 `/metrics`	路径写错（如 `/metric` 少 s）、应用暴露路径不同	使用 `curl` 或 `wget` 直接访问 Pod IP:Port/path 验证
`scheme`	HTTP 或 HTTPS，默认为 HTTP	应用使用 HTTPS 但配置为 HTTP，导致 TLS 握手失败	检查应用 metrics 端点协议，必要时配置 `tlsConfig`

快速验证：在集群内启动一个临时 Pod（如 kubectl run test-pod --image=curlimages/curl --rm -it --restart=Never -- sh），然后使用 curl http://<service-name>.<namespace>:<port>/<path> 直接测试 metrics 端点是否可达且返回 Prometheus 格式数据。

4.4 综合排查流程：从配置到抓取的链路验证

以下 SVG 图展示了从 ServiceMonitor/PodMonitor 配置到 Prometheus 实际抓取目标的完整链路，以及各环节的排查要点。

4.5 典型错误案例与修复对照

错误现象	可能原因	修复方法
Targets 页面显示 0 targets	标签选择器未匹配到任何 Service/Pod；命名空间选择错误	检查 selector 和 namespaceSelector 配置；使用 `kubectl get svc -l <labels> -A` 验证匹配
Targets 显示 down，连接超时	端口号错误；Pod 未监听该端口；网络策略阻止	确认 port/targetPort 与实际容器端口一致；检查 NetworkPolicy
Targets 显示 down，HTTP 404	path 配置错误；应用 metrics 端点路径不同	使用 curl 直接测试；查看应用文档确认 metrics 路径
Targets 显示 up，但数据为空或格式错误	relabel 规则过滤了所有指标；应用未暴露正确 metrics	检查 relabel_configs 中的 keep/drop 规则；直接访问端点验证输出
部分目标缺失，部分正常	matchExpressions 条件过于严格；某些 Pod 标签不完整	使用 `kubectl get pod --show-labels` 对比所有 Pod 标签

4.6 配置验证与自动化检查

在 CI/CD 流程中集成配置验证，可以从源头减少误差预算台账数据不准的问题。推荐以下工具和方法：

promtool check service-monitor / pod-monitor：Prometheus 官方工具，可验证 CRD 配置的语法和逻辑正确性。
conftest 或 OPA：编写 Rego 策略，强制要求 ServiceMonitor 必须设置 namespaceSelector、端口名称必须存在于对应 Service 中。
Kubernetes 准入控制器：使用 ValidatingWebhookConfiguration 拦截不合规的 ServiceMonitor/PodMonitor 创建请求。

自动化检查示例（promtool）：

# 检查 ServiceMonitor 配置
promtool check service-monitor /path/to/service-monitor.yaml

# 检查 PodMonitor 配置
promtool check pod-monitor /path/to/pod-monitor.yaml

# 输出示例（正常）
# SUCCESS: 1 service-monitor checked, 0 errors

# 输出示例（错误）
# ERROR: service-monitor "my-app" is invalid: spec.namespaceSelector: Required value

通过系统性地排查标签匹配、命名空间选择、端口与路径配置这三个维度，结合 Prometheus Targets 页面和 Operator 日志的反馈，可以快速定位 ServiceMonitor 与 PodMonitor 配置中的问题，确保抓取链路正确，为误差预算台账的准确性奠定基础。