GoFr 服务 Kubernetes 水平自动扩缩容基于 CPU 与 Prometheus 自定义指标的 HPA v2 实战指南【免费下载链接】gofrAn opinionated GoLang framework for accelerated microservice development. Built in support for databases and observability.项目地址: https://gitcode.com/GitHub_Trending/go/gofrGoFr 框架开箱即用地在METRICS_PORT默认 2121暴露 Prometheus 格式指标配合 Kubernetes HPA v2 与 prometheus-adapter即可为 GoFr 服务构建「先 CPU、后自定义请求速率」的两级自动扩缩容方案。本文以docs/guides/horizontal-pod-autoscaler/page.md为核心骨架结合 GoFr 源码中指标注册、中间件记录与健康探针的底层实现完整讲解从 metrics-server 启用、Deployment 资源声明、HPA v2 清单编写、prometheus-adapter 规则配置到压测验证的全流程并剖析冷启动、资源请求缺失、无法缩容到零等常见坑点。何时使用 HPA当流量具有突发性而固定副本数在空闲期过度供给、在峰值期又供应不足时就应该考虑 HPA。纯 CPU 自动扩缩容对 I/O 密集型负载往往反应滞后——一个正在等待下游 HTTP 调用的 GoFr 服务 CPU 占用很低但请求队列可能已经很长。基于 QPS 或延迟的自定义指标 HPA 恰好能弥合这一差距。需要特别说明的是对于事件驱动型负载Kafka、NATS、MQTT 订阅者HPA 无法缩容到零副本这类场景应交给 KEDA 的对应 scaler 处理KEDA 的 Kafka/NATS scaler 还支持批次之间的缩零。GoFr 提供的 HPA 指标基础GoFr 在METRICS_PORT默认 2121上的/metrics端点发布一套默认的 HTTP、数据源与运行时指标无需任何额外配置详细清单见 可观测性快速入门。指标端点的底层实现METRICS_PORT的默认值定义在 pkg/gofr/default.goconst ( defaultHTTPPort 8000 defaultGRPCPort 9000 defaultMetricPort 2121 defaultMCPPort 8200 )指标服务器的初始化逻辑在 pkg/gofr/factory.go// initMetricsServer initializes the metrics server based on configuration. // If METRICS_PORT is explicitly set to 0, the metrics server is disabled. func (a *App) initMetricsServer() { metricsPortStr : a.Config.Get(METRICS_PORT) if metricsPortStr 0 { a.container.Logger.Logf(Metrics server is disabled (METRICS_PORT0)) return } port, err : strconv.Atoi(metricsPortStr) if err ! nil || port 0 { port defaultMetricPort } ... }从源码可以看出三个关键行为METRICS_PORT0会整体禁用指标服务器在 gofr_test.go 中有对应测试非数字或非法端口会回退到默认 2121端口被占用时框架会直接Fatalf退出。指标服务器本身是一个独立的http.Server处理器由metrics.GetHandler(c.Metrics())提供见 pkg/gofr/metrics_server.go。app_http_response 直方图RPS 指标的来源HTTP 层的关键指标是app_http_response——一个直方图。它在容器初始化时注册见 pkg/gofr/container/container.go{ // HTTP metrics httpBuckets : []float64{.001, .003, .005, .01, .02, .03, .05, .1, .2, .3, .5, .75, 1, 2, 3, 5, 10, 30} c.Metrics().NewHistogram(app_http_response, Response time of HTTP requests in seconds., httpBuckets...) ... }每个 HTTP 请求都会经过 pkg/gofr/http/middleware/metrics.go 中的Metrics中间件记录一次app_http_response观测值并携带path、method、status三个标签。因此请求速率可以这样推导rate(app_http_response_count[1m])即「过去 1 分钟内每秒处理的请求数」。GoFr 的Metrics中间件还做了性能优化对已模板化的路由缓存预构建的测量选项避免每次请求重复构建属性切片见 metrics.go 中的optionRecorder。此外该中间件会跳过/graphql端点GraphQL 有独立的app_graphql_*指标见 metrics.go避免重复计数。除了默认指标你还可以通过NewCounter、NewHistogram等 API 发布自定义业务指标详细做法参见 发布自定义指标。Pod 模板必须暴露指标端口让 Prometheus以及后续的 prometheus-adapter能抓取到 GoFr 指标Pod 模板中必须声明指标端口ports: - name: http containerPort: 8000 - name: metrics containerPort: 2121如果集群使用 prometheus-operator可以配套ServiceMonitor来定义抓取规则也可以参考仓库中 examples/http-server/docker 目录下的 Prometheus 抓取配置prometheus.yml 与 docker-compose.yaml以及 examples/using-custom-metrics/docker 中的采集链示例。分步操作为 GoFr 服务启用 HPA整体流程可概括为六个步骤启用 metrics-serverkubectl applymetrics-server 清单或启用 minikube 的对应插件让 HPA 能读取 Pod 的 CPU 与内存设置资源请求在 GoFr Deployment 上声明resources.requests.cpu——HPA 的利用率计算基于usage / request应用基于 CPU 的 HPA使用autoscaling/v2API 创建 HPA在 CPU 上设置averageUtilization目标60% 是合理的起步值并依据基线流量设定 min/max 副本数调优扩缩容行为设置behavior.scaleUp.stabilizationWindowSeconds吸收突发流量设置behavior.scaleDown避免副本抖动可选接入自定义指标安装 prometheus-adapter 并编写规则将app_http_response_count暴露为可供 HPA 引用的自定义指标压测验证用 hey 或 k6 生成负载观察kubectl get hpa确认副本数按预期伸缩。关于 Deployment 资源请求的源码依据HPA 的 CPU 利用率公式是usage / request因此resources.requests.cpu缺失时CPU 类扩缩容会被静默禁用。同时 GoFr 服务应声明minReadySeconds并配置readinessProbe指向/.well-known/health避免尚未就绪的新 Pod 被计入容量。GoFr 内置的/.well-known/health端点是无认证的公开健康检查端点只返回最小化的非敏感信息其实现见 pkg/gofr/health.go。prometheus-adapter 规则把指标桥接到 custom.metrics.k8s.ioHPA 无法直接查询 Prometheus需要 prometheus-adapter 将 Prometheus 序列暴露为custom.metrics.k8s.ioAPI。下面是一条最小规则为 GoFr Deployment 提供按 Pod 维度的每秒请求数rules: - seriesQuery: app_http_response_count{namespace!,pod!} resources: overrides: namespace: { resource: namespace } pod: { resource: pod } name: matches: ^app_http_response_count$ as: http_requests_per_second metricsQuery: | sum(rate(.Series{.LabelMatchers}[1m])) by (.GroupBy)规则要点seriesQuery限定在带namespace、pod标签的app_http_response_count序列上这是 GoFr 指标能被按 Pod 聚合的前提resources.overrides把 Prometheus 的namespace、pod标签映射为 Kubernetes 资源维度name.as将指标重命名为http_requests_per_secondHPA 清单中引用的正是这个名字metricsQuery用rate(...[1m])把直方图的_count序列换算成每秒请求速率并按 Pod 维度求和。配置完成后可用以下命令验证自定义指标 API 是否已暴露kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1/namespaces/ns/pods/*/http_requests_per_second注意prometheus-adapter 默认每 30 秒向 Prometheus 轮询一次新出现的指标序列最多需要约 1 分钟才会出现在custom.metrics.k8s.io中。HPA v2 清单CPU 自定义请求速率双指标下面的清单同时使用 CPU 利用率与每秒请求数两个指标并配置了防抖动的扩缩容行为apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: orders-api namespace: prod spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: orders-api minReplicas: 3 maxReplicas: 30 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 70 - type: Pods pods: metric: name: http_requests_per_second target: type: AverageValue averageValue: 50 behavior: scaleUp: stabilizationWindowSeconds: 30 policies: - type: Percent value: 100 periodSeconds: 30 scaleDown: stabilizationWindowSeconds: 300 policies: - type: Percent value: 25 periodSeconds: 60字段说明CPU 指标type: Resourcename: cpuaverageUtilization: 70表示目标平均 CPU 利用率为 70%计算基于usage / requests.cpu自定义指标type: Pods表示按 Pod 维度取平均averageValue: 50表示每个 Pod 平均每秒处理 50 个请求behavior块是「抖动型 HPA」与「稳定型 HPA」的分水岭较短的scaleUp.stabilizationWindowSeconds30 秒让扩容快速响应突发较长的scaleDown.stabilizationWindowSeconds300 秒在流量短暂回落时防止副本反复伸缩。扩缩容策略使用百分比形式每 30 秒最多扩容 100%每 60 秒最多缩容 25%。常见坑点与规避方式冷启动HPA 不应把未就绪 Pod 计入容量新启动的 GoFr Pod 在对外提供服务前需要完成 启动钩子如缓存预热、数据库迁移等。因此 Deployment 上应设置minReadySeconds并配置指向/.well-known/health的readinessProbe让 HPA 只把就绪 Pod 计入当前容量。资源请求缺失会导致 CPU 扩缩容静默失效HPA 的 CPU 计算是usage / request。如果 Deployment 省略了resources.requests.cpu基于 CPU 的扩缩容会被静默禁用——这是最常见的「HPA 不工作」原因之一。HPA 无法缩容到零minReplicas: 0会被 API 服务器拒绝。如果你需要为 cron 类负载提供缩零能力应使用 KEDA而不是 HPA。HPA 显示unknown的原因kubectl describe hpa输出的Metrics块会给出当前值 vs 目标值单位不匹配例如m与整数之间是 HPA 报告unknown的最常见原因。对于自定义指标显示unknown通常有三种可能prometheus-adapter 尚未发现该序列、HPA 清单中的指标名与规则的as:值不一致、或 Prometheus 序列上缺少namespace/pod标签。压测与验证应用 HPA 后用 hey 或 k6 生成负载并通过以下命令观察扩缩容行为kubectl get hpa orders-api -n prod kubectl describe hpa orders-api -n prod kubectl top pods -n prod -l apporders-apikubectl get hpa的TARGETS列显示当前值/目标值如25%/70%与12/50kubectl describe会打印Metrics块的详细计算过程是排查单位不匹配等问题的第一现场kubectl top pods用于确认实际资源用量与副本伸缩是否一致。常见问题GoFr 需要为 HPA 做任何代码改动吗不需要。GoFr 已经在METRICS_PORT默认 2121暴露 Prometheus 格式指标HPA 的全部配置都在 prometheus-adapter 规则与 HPA 清单中完成。可以用 HPA 扩缩容 GoFr 的 Pub/Sub 订阅者吗HPA 可以基于 CPU 扩缩容但基于消费滞后的扩缩容更适合交给 KEDA 的 Kafka/NATS scaler 处理它还能在批次之间缩容到零。为什么我的 HPA 对自定义指标显示unknown要么 prometheus-adapter 还没发现该序列要么 HPA 清单中的指标名与规则as:值不匹配要么 Prometheus 序列上缺少namespace、pod标签。延伸阅读可观测性快速入门GoFr 内置日志、追踪与指标的完整说明发布自定义指标为 HPA 提供更多业务维度的自定义计数器与直方图启动钩子理解冷启动期间执行的预热与迁移逻辑examples/http-server包含 Docker Compose 与 Prometheus 抓取配置的完整 HTTP 服务示例examples/using-custom-metrics自定义指标与 Prometheus、OTel Collector 的集成示例【免费下载链接】gofrAn opinionated GoLang framework for accelerated microservice development. Built in support for databases and observability.项目地址: https://gitcode.com/GitHub_Trending/go/gofr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考