📚 课程目录第4章自定义指标与Prometheus Adapter

4. 自定义指标与 Prometheus Adapter：自定义指标 API、Prometheus Adapter 架构、适配器配置原理

在 Kubernetes 原生 HPA 仅支持 CPU/内存等资源指标，无法感知业务队列深度、请求延迟、连接数等业务信号。本章引入 自定义指标（Custom Metrics） 与 Prometheus Adapter，将 Prometheus 中任意时序数据转换为 Kubernetes 可消费的指标 API，实现数据驱动的控制面弹性伸缩。

4.1 自定义指标 API 体系

Kubernetes 指标 API 分为三层，每一层对应不同的指标来源与用途：

API 层	资源类型	指标来源	典型用途
Resource Metrics	metrics.k8s.io	Metrics Server（cAdvisor）	CPU、内存实时使用率
Custom Metrics	custom.metrics.k8s.io	Prometheus Adapter / 第三方适配器	业务自定义指标（队列长度、QPS、延迟）
External Metrics	external.metrics.k8s.io	云厂商 / 外部系统适配器	云服务指标（SQS 深度、LB 连接数）

关键认知： HPA 通过 custom.metrics.k8s.io 和 external.metrics.k8s.io 获取指标，不再依赖 Metrics Server。Prometheus Adapter 正是实现 custom.metrics.k8s.io 的标准组件。

4.2 Prometheus Adapter 架构

Prometheus Adapter 作为 Kubernetes API 扩展，运行在集群内部，通过 APIService 对象注册自定义指标 API。其核心架构包含三个模块：

  架构要点：
  采集层：向 Prometheus 发起 PromQL 查询，支持聚合、过滤、速率计算。
适配层：将 Prometheus 返回的时序数据映射为 Kubernetes 指标格式（series → metric name + labels）。
API 暴露层：通过 APIService 注册 custom.metrics.k8s.io，HPA 直接调用。

4.3 适配器配置原理

Prometheus Adapter 通过 --config 或 ConfigMap 加载 YAML 配置，核心是 rules 字段，定义 PromQL 到 Kubernetes 指标的映射规则。配置结构如下：

rules:
  # 自定义指标规则
  - seriesQuery: 'http_requests_total{namespace!="",pod!=""}'
    resources:
      overrides:
        namespace: { resource: "namespace" }
        pod:       { resource: "pod" }
    name:
      matches: "^(.*)_total$"
      as: "${1}_per_second"
    metricsQuery: 'sum(rate(<<.Series>>{<<.LabelMatchers>>}[2m])) by (<<.GroupBy>>)'

配置字段	作用	示例说明
`seriesQuery`	PromQL 查询，发现可用指标	筛选包含 namespace/pod 标签的指标
`resources.overrides`	将 Prometheus 标签映射为 K8s 资源	`pod` → `resource: "pod"`
`name.matches / name.as`	正则转换指标名称	`http_requests_total` → `http_requests_per_second`
`metricsQuery`	最终 PromQL 模板，HPA 调用时填充	使用 `<<.Series>>` 和 `<<.LabelMatchers>>` 模板变量

常见陷阱：

标签匹配失败：Prometheus 中标签名必须与 resources.overrides 一致，否则 HPA 返回 "no matching metrics found"。
指标名称冲突：多个规则输出相同 as 名称会导致 API 注册失败。
性能问题：seriesQuery 返回大量 series 时，Adapter 启动会变慢，建议使用 labelSelector 过滤。

4.4 部署与验证流程

部署 Prometheus Adapter：使用 Helm 或 YAML 部署，配置 APIService 和 RBAC。
编写 ConfigMap：定义 rules，映射业务指标（如 kafka_consumer_lag、nginx_connections_active）。
验证 API 注册：kubectl get apiservice | grep custom 确认状态为 True。
测试指标查询：kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1 查看可用指标列表。
HPA 引用自定义指标：在 HPA 的 metrics 字段中指定 type: Pods 或 type: Object。

生产建议： 使用 --metrics-relist-interval 控制 Adapter 重新发现指标的频率（默认 5 分钟），对于高频变化的业务指标可缩短至 1 分钟，但需注意 Prometheus 查询压力。