3. ServiceMonitor 基础定义：apiVersion、kind、metadata、spec 结构详解

ServiceMonitor 是 Prometheus Operator 引入的自定义资源（CRD），用于声明式地定义 Prometheus 应监控哪些 Service 端点。理解其基础定义结构是标签治理的前提——因为标签选择逻辑、端点匹配规则、重命名行为都直接由 spec 中的字段控制。本章将逐层拆解 ServiceMonitor 的四个核心组成部分：apiVersion、kind、metadata 和 spec，并明确区分必填字段与可选字段。

3.1 顶层结构概览

一个完整的 ServiceMonitor YAML 遵循标准的 Kubernetes 资源格式。以下是一个最小可用的示例，展示了四个顶层字段的排列关系：

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: example-monitor
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: my-service
  endpoints:
  - port: http-metrics
    interval: 30s

下面通过一张结构图直观展示 ServiceMonitor 的顶层字段及其层级关系：

3.2 apiVersion 与 kind：资源标识

3.3 metadata：元数据定义

metadata 字段遵循 Kubernetes 通用元数据规范，用于标识和分类 ServiceMonitor 资源。

* namespace 在 YAML 中通常建议显式声明，避免因 kubectl 上下文不同导致资源创建位置错误。

3.4 spec：核心配置结构

spec 是 ServiceMonitor 的功能主体，定义了 Prometheus 如何发现目标、采集指标以及处理标签。以下按字段重要性分组说明。

3.4.1 必填字段

3.4.2 常用可选字段

3.5 必填字段与可选字段的完整清单

以下流程图帮助快速判断一个 ServiceMonitor 定义是否合法：

3.6 实战示例：完整定义与字段说明

以下是一个生产级 ServiceMonitor 示例，包含必填字段和常用可选字段：

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: payment-service-monitor
  namespace: monitoring
  labels:
    release: prometheus-stack      # 用于 Prometheus 的 serviceMonitorSelector 匹配
    team: payment                   # 团队标签，便于资源分类
    environment: production         # 环境标签
spec:
  # --- 必填字段 ---
  selector:
    matchLabels:
      app: payment-service          # 选择 app=payment-service 的 Service
    matchExpressions:               # 可选：表达式匹配
      - key: tier
        operator: In
        values: ["backend", "critical"]
  endpoints:
    - port: metrics                 # 引用 Service 中定义的端口名称
      interval: 30s
      scrapeTimeout: 10s
      path: /metrics
      scheme: http
      # 重标签规则（标签治理核心）
      relabelings:
        - sourceLabels: [__meta_kubernetes_pod_node_name]
          targetLabel: node
          action: replace
      metricRelabelings:
        - sourceLabels: [__name__]
          regex: "go_.*"
          action: drop               # 丢弃所有 go_ 开头的指标

  # --- 可选字段 ---
  namespaceSelector:
    matchNames:
      - production                   # 只允许选择 production 命名空间的 Service
  jobLabel: "app"                    # 将 ServiceMonitor 的 app 标签值作为 job 标签
  targetLabels:
    - app
    - version                        # 从 Service 复制 app 和 version 标签到目标
  podTargetLabels:
    - pod-template-hash              # 从 Pod 复制 pod-template-hash 标签
  sampleLimit: 50000                 # 每个端点最多采集 50000 个样本

3.7 常见错误与避坑指南

• selector 为空或缺失： 如果 spec.selector 为空，Prometheus Operator 不会选择任何 Service，导致抓取目标为空。必须至少提供 matchLabels 或 matchExpressions。
• endpoints 中 port 与 targetPort 混淆： port 引用 Service 中定义的端口名称（string），targetPort 引用 Pod 中的端口号（int）或名称。两者只需指定其一，同时指定可能导致歧义。
• namespaceSelector 未配置导致跨命名空间失败： 默认情况下，ServiceMonitor 只能选择同一命名空间的 Service。如果需要跨命名空间选择，必须显式配置 namespaceSelector。
• jobLabel 指向不存在的标签： 如果 jobLabel 指定的标签在 ServiceMonitor 的 metadata 中不存在，Prometheus 会使用默认的 job 名称（ServiceMonitor 名称）。建议始终确保标签存在。
• sampleLimit 设置过小： 如果应用暴露大量指标，过小的 sampleLimit 会导致部分指标被静默丢弃。建议先观察正常采集量，再设置合理的上限。

3.8 本章小结