4. 自定义指标架构总览：Prometheus + Adapter + HPA 的端到端数据流
在基于连接池水位进行弹性伸缩的场景中，数据从业务 Pod 的指标暴露到 HPA 做出扩缩容决策，需要经过一条完整的采集、转换、适配链路。理解这条链路的每个环节，是正确配置自定义指标的前提。
下图展示了 Prometheus → Adapter → HPA 三个核心组件之间的数据流转关系：
4.1 数据流各环节职责
整个链路可以拆解为五个关键环节，每个环节承担特定的数据转换职责：
| 环节 | 组件 | 核心职责 | 数据形态 |
|---|---|---|---|
| ① 指标暴露 | 业务 Pod | 在 /metrics 端点输出连接池使用量、最大连接数、等待队列长度等指标 | Prometheus 文本格式（Gauge/Histogram） |
| ② 指标采集 | Prometheus Server | 按配置的 scrape_interval 定期拉取 Pod 指标，存储为时间序列 | 时间序列数据（TSDB） |
| ③ 指标适配 | Metrics Adapter | 通过 PromQL 查询 Prometheus，将结果转换为 Kubernetes 自定义指标格式 | custom.metrics.k8s.io API 资源 |
| ④ 指标查询 | Kubernetes API Server | 提供标准的 custom-metrics API 端点，供 HPA 查询 | MetricValueList JSON 响应 |
| ⑤ 弹性决策 | HPA Controller | 周期性获取当前指标值，与目标值比较，计算期望副本数并更新 Deployment/StatefulSet | Replica 数字（整数） |
关键理解：Adapter 是整个架构的"翻译官"。Prometheus 存储的是原始时间序列数据，而 HPA 需要的是符合
custom.metrics.k8s.io 接口规范的指标值。Adapter 通过配置的 PromQL 查询语句，完成从"指标名+标签"到"当前值"的转换。
4.2 连接池水位指标在数据流中的形态变化
以连接池水位为例，观察同一个指标在不同环节的表示形式：
| 环节 | 指标表示 | 示例值 |
|---|---|---|
| Pod /metrics | db_connections_in_use{pool="primary",pod="app-7d8f9c"} |
42 |
| Prometheus TSDB | db_connections_in_use{instance="10.0.0.5:8080",pool="primary"} |
42 @ timestamp |
| Adapter PromQL 结果 | avg(db_connections_in_use) by (pod) |
42.0 |
| custom-metrics API | /apis/custom.metrics.k8s.io/v1beta1/namespaces/default/pods/*/db_connections_in_use |
{"value": "42"} |
| HPA 决策 | 当前值 / 目标值 → 期望副本数 | 42 / 30 = 2 → 期望 2 个副本 |
4.3 关键配置点
要使这条数据流正常工作，需要在三个组件上完成对应的配置：
- Pod 端：应用必须暴露 Prometheus 格式的指标，且指标命名清晰（如
pool_connections_active、pool_connections_idle）。 - Prometheus 端：配置 ServiceMonitor 或 PodMonitor 确保能发现并抓取目标 Pod 的 /metrics 端点。
- Adapter 端：编写 adapter 配置文件，定义 PromQL 查询、指标名称映射、返回的标签（通常保留 pod 标签用于 HPA 按 Pod 查询）。
常见误区：很多初学者只配置了 Prometheus 采集，却忽略了 Adapter 端的 PromQL 查询必须返回
{pod="xxx"} 标签。HPA 按 Pod 查询指标时，如果 Adapter 返回的指标缺少 pod 标签，会导致 HPA 无法正确获取每个 Pod 的当前水位值，从而触发"指标不可用"错误。
4.4 数据流时序与延迟
理解数据流中的延迟累积，有助于设置合理的 HPA 指标窗口和扩缩容阈值：
延迟风险提示：如果连接池水位在短时间内剧烈波动（如秒级突发流量），上述 60 秒的端到端延迟可能导致 HPA 响应滞后。对于这种场景，建议配合 KEDA 或使用 Direct Pod Scrape 方式缩短延迟，或者通过调整 HPA 的
behavior.scaleUp.stabilizationWindowSeconds 来平衡响应速度和稳定性。
4.5 架构优势与适用场景
这种 Prometheus + Adapter + HPA 的架构之所以成为 Kubernetes 自定义指标弹性伸缩的事实标准，主要得益于以下特性：
- 解耦性：指标采集、存储、转换、决策各司其职，任一组件可独立升级或替换。
- 扩展性：Adapter 支持任意 PromQL 表达式，可以实现复杂的指标聚合（如连接池使用率 = 活跃连接数 / 最大连接数）。
- 标准化：最终暴露的 custom-metrics API 是 Kubernetes 原生接口，HPA 无需关心底层指标来源。
- 生态兼容：Prometheus 生态中的 Exporter、ServiceMonitor、Recording Rules 等工具均可复用。