kubernetes_sd 是什么
kubernetes_sd_configs 让 Prometheus 直接以 Kubernetes API 为数据源发现抓取目标：按 role 生成候选目标，每个候选带一组 __meta_kubernetes_* 元标签，再用 relabel_configs 筛选、改写后成为真正的抓取目标。Pod 频繁重建、IP 不断变化的集群里，用服务发现替代静态列表是标准做法，它也是 Prometheus Operator 生成抓取配置的底层机制。
基本信息
| 适用平台 | Kubernetes（Prometheus 2.x） |
|---|---|
| 配置位置 | scrape_configs 下的 kubernetes_sd_configs |
| 认证方式 | 集群内用 ServiceAccount，集群外用 kubeconfig |
| 关键机制 | role 生成候选 + relabel 筛选 |
| 元标签前缀 | __meta_kubernetes_ |
| 常用 role | node / pod / service / endpoints / ingress |
典型使用场景
- 抓取集群内应用的 /metrics：用 pod 或 endpoints role 发现真实后端
- 采集节点资源指标：用 node role 发现 kubelet 的地址与端口
- 用 Pod 注解（prometheus.io/scrape）让应用自助声明是否被抓取
- 按命名空间或标签做多租户隔离，只采本团队的目标
- 集群外 Prometheus 通过 API Server 发现集群内目标并统一接入
- 配合 kube-state-metrics 与 cAdvisor 补齐对象状态与资源用量两个视角
按 Pod 注解筛选抓取目标
按 Pod 注解筛选抓取目标
- job_name: kubernetes-pods
kubernetes_sd_configs:
- role: pod # 按 Pod 生成候选目标
relabel_configs:
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
action: keep # 只保留声明要抓取的 Pod
regex: 'true'
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
target_label: __metrics_path__ # 覆盖默认 /metrics 路径
regex: '(.+)'
- source_labels: [__meta_kubernetes_namespace]
target_label: namespace # 保留租户维度便于查询常用 role
| role | 对应的目标 | 典型用途 |
|---|---|---|
| node | 集群节点（kubelet） | 节点资源指标 |
| pod | Pod IP 与容器端口 | 应用指标抓取 |
| service | Service 虚拟 IP | Service 级端点发现 |
| endpoints | Endpoints 的每个后端 | 按真实后端抓取 |
| ingress | Ingress 规则 | 入口探测类场景 |
生产中通常由 Prometheus Operator 或平台自动化生成这套配置，手写时优先从官方示例起步，避免 relabel 规则遗漏。
endpoints role 的候选是每个真实后端地址，比 service role 的虚拟 IP 更贴近实际流量；直接用虚拟 IP 抓取会丢失单实例粒度。
relabel 之后还有 metric_relabel_configs，它作用于抓到的样本而非目标；两者配合能同时控制目标数量与序列数量。
role 的选择决定标签维度：pod role 带 pod、namespace 与 container 维度，endpoints role 带 service 与 endpoint 维度，按需要的下钻粒度挑 role。
集群规模大时服务发现本身也有开销：API Server 的 watch 连接、元标签数量都会随对象数增长，抓取频率与范围要一并评估。