Golang自定义K8s HPA指标实现方法

本文深入剖析了在 Kubernetes 中使用 Golang 实现自定义 HPA 指标（如 Prometheus 的 `http_requests_total`）时常见却易被误解的痛点，直击 metrics-server 与 custom-metrics-apiserver 职责分离这一根本原因，系统性地拆解了 `kubectl top pods` 报错、HPA 显示 `unknown`、Adapter 查询超时、指标匹配失败等典型问题背后的机制，并给出精准可落地的排查路径：从 APIService 可用性验证、TLS/RBAC/网络连通性检查，到 Go 客户端超时配置、JSON 响应格式合规性、Prometheus 查询语义细节及缓存优化，帮你绕过 K8s metrics 生态中那些隐晦的“坑”，真正实现稳定、可靠、可调试的自定义指标驱动扩缩容。

为什么 CustomMetricsAdapter 启动后 kubectl top pods 仍报错 “unable to fetch metrics”

根本原因不是适配器没跑起来，而是 K8s 的 metrics-server 和 custom-metrics-apiserver 没对齐——前者只管 metrics.k8s.io（CPU/内存），后者才管 custom.metrics.k8s.io。你看到的报错，大概率是客户端在请求 custom.metrics.k8s.io 时被拒绝或超时，而非指标本身没采集到。

实操建议：

• 先确认 apiservice 状态：kubectl get apiservice v1beta1.custom.metrics.k8s.io -o wide，看 AVAILABLE 列是否为 True；如果不是，重点查 CustomMetricsAdapter Pod 日志里有没有 TLS 证书校验失败、Service DNS 解析失败、或 RBAC 权限缺失（尤其是 system:auth-delegator ClusterRoleBinding）
• 别用 kubectl top pods 测试自定义指标——它只走 metrics.k8s.io。正确验证方式是：kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/default/pods/*/http_requests_total"
• 如果你的 Adapter 是基于 k8s.io/kube-state-metrics 或 Prometheus 提供的数据源，注意它的 --prometheus-url 必须能被集群内 Pod 网络访问（比如用 http://prometheus-operated.monitoring.svc:9090，而不是 localhost:9090）

如何让 HPA 正确识别 http_requests_total 这类 Prometheus 指标

HPA 不会自动“猜”你的指标含义，必须通过 metricSelector 和 name 显式绑定。Prometheus 中一个指标名（如 http_requests_total）可能对应多个时间序列（不同 job、pod 标签），HPA 需要精确指定聚合维度和目标对象。

实操建议：

• 写 HPA YAML 时，metrics 下必须用 type: Pods 或 type: Object，不能只写 type: External（那是给集群外服务用的）
• 例如按 Pod 维度扩缩：

  metrics:
  - type: Pods
    pods:
      metric:
        name: http_requests_total
      target:
        type: AverageValue
        averageValue: 100m

  注意单位：100m 表示每秒 0.1 次请求，不是 100 次
• 如果想按 Deployment 总量扩缩，要用 type: Object 并指定 describedObject，且指标名需带 {namespace}/{name} 前缀（Adapter 默认行为），否则匹配不到
• 检查 Adapter 日志中是否有类似 "no matching series for selector" 的警告——说明 Prometheus 查询返回空，常见于 label 值拼写错误（比如把 app.kubernetes.io/name 写成 app）

Go 实现的 CustomMetricsAdapter 为何总卡在 GetMetricBySelector 超时

Go 代码里最容易忽略的是 HTTP 客户端默认没有设置超时，而 Prometheus 查询可能因数据量大、存储响应慢，在 30 秒后被 Kubernetes API Server 主动断连，导致整个 metrics 请求失败。

实操建议：

• 在初始化 Prometheus client 时，必须显式设置 Timeout 和 RoundTripper：

  client, err := api.NewClient(api.Config{
      Address: "http://prometheus.default.svc:9090",
      RoundTripper: &http.Transport{
          DialContext: (&net.Dialer{
              Timeout:   5 * time.Second,
              KeepAlive: 30 * time.Second,
          }).DialContext,
          TLSHandshakeTimeout: 5 * time.Second,
      },
      // 注意这里！
      Timeout: 10 * time.Second,
  })

• 避免在 GetMetricBySelector 中做同步阻塞操作（比如调用另一个 HTTP 服务、读本地文件）。所有 IO 必须带 context 超时，并尽早 return error
• K8s 会并发调用你的 Adapter 接口，如果 Prometheus 查询没加缓存或限流，容易触发 429。建议在 Go 层加一层简单 LRU 缓存（比如用 github.com/hashicorp/golang-lru），缓存 key 包含查询时间范围、label selector 和 metric name

HPA 扩容后 Pod 数没变，但 kubectl get hpa 显示 Target 和 Current 都是 unknown

这不是 HPA 逻辑问题，而是指标链路某处断了：从 Adapter 返回数据 → K8s metrics cache → HPA controller 获取 → 计算副本数，其中任意一环失败都会卡在 unknown。最常出问题的是 Adapter 返回的 JSON 结构不符合 K8s 要求。

实操建议：

• 抓包看 Adapter 实际返回的 HTTP body：它必须严格符合 custom.metrics.k8s.io/v1beta1 的 OpenAPI schema，特别是 items[].value 字段必须是字符串（如 "123"），不能是数字（123）或空字符串
• 检查 Adapter 是否正确设置了 Content-Type: application/json，少这个 header 会导致 K8s 解析失败并静默丢弃响应
• HPA controller 默认每 15 秒拉一次指标，但第一次拉取失败后，它不会立即重试——要等下一个周期。所以改完 Adapter 后，至少等 20 秒再 kubectl get hpa，别刚重启就查
• 如果用了 Prometheus recording rule（比如 job:http_requests_total:rate5m），确保 Adapter 查询时用的是 rule 名，而不是原始指标名，否则查不到

事情说清了就结束。真正卡住人的，往往不是 Adapter 怎么写，而是 K8s metrics 生态里那几层隐式依赖：APIService 状态、TLS 证书链、Prometheus 查询语义、HPA 的缓存周期、甚至 kube-apiserver 的日志级别（默认不打印 metrics 相关 debug 信息）。调的时候别只盯着 Go 代码。

好了，本文到此结束，带大家了解了《Golang自定义K8s HPA指标实现方法》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！