Prometheus Adapter Helm Chart 实战：为 Kubernetes HPA 接入自定义、外部与资源指标

本篇技术指南围绕 Prometheus Community 仓库中的 prometheus-adapter Helm Chart 展开，讲解如何通过该 Chart 将 Prometheus 中的指标暴露为 Kubernetes 的 Custom Metrics、External Metrics 与 Resource Metrics API，从而驱动 Horizontal Pod Autoscaler（HPA）实现基于业务指标的弹性伸缩。读完本文，你将掌握该 Chart 的安装/升级/卸载方式、三类指标规则（rules.custom、rules.external、rules.resource）的完整配置写法、Prometheus 服务端点与证书的接入要点，以及 Chart 内部如何通过 ConfigMap 与 APIService 资源把规则落地为可被 HPA 调用的 API。

为什么需要 Prometheus Adapter

Kubernetes 内置的 metrics-server 类组件只提供基于 CPU 和内存的资源指标，而业务场景往往需要根据 QPS、队列深度、错误率等自定义指标来决定扩容缩容。Prometheus Adapter 正是承担"桥接"角色的组件：它持续从 Prometheus 拉取指标，按照配置的规则将指标映射到 Kubernetes 的三种 Metrics API，让 HPA 可以像使用内置指标一样使用来自 Prometheus 的业务指标。

本仓库中的prometheus-adapterChart（当前版本 5.3.0，对应 Chart.yaml 中 appVersion v0.12.0）封装了部署该 Adapter 所需的全部 Kubernetes 资源：Deployment、Service、ConfigMap（存放规则配置）、三类 APIService、RBAC 以及可选的 cert-manager 证书签发，并补充了 metrics-server 所不具备的指标维度。

安装前提

• 需要 Kubernetes 1.21 及以上版本。从 Chart 5.0.0 起移除了对废弃 APIpolicy/v1beta1（用于 PodDisruptionBudget）的支持，同时移除了废弃的PodSecurityPolicy资源，因此低版本集群无法直接使用。
• 集群中需要已有可访问的 Prometheus 服务（默认假设为http://prometheus.default.svc:9090，可通过prometheus.url/prometheus.port调整）。

安装、升级与卸载

获取 Chart

该 Chart 同时以 OCI Artifact 和传统 Helm Repository 两种方式分发：

• OCI Artifact：oci://ghcr.io/prometheus-community/charts/prometheus-adapter
• Helm Repository：https://prometheus-community.github.io/helm-charts，Chart 名为prometheus-adapter

安装

helm install [RELEASE_NAME] oci://ghcr.io/prometheus-community/charts/prometheus-adapter

[RELEASE_NAME]替换为你的发布名称。安装完成后，Chart 会创建一套完整的组件：Deployment（默认 1 个副本）、Service（ClusterIP、端口 443 映射到容器 https 端口 6443）、承载规则配置的 ConfigMap，以及根据规则启用情况创建对应的 APIService。可通过helm show values查看全部可配置项：

helm show values oci://ghcr.io/prometheus-community/charts/prometheus-adapter

卸载

helm uninstall [RELEASE_NAME]

该命令会删除 Chart 创建的所有 Kubernetes 组件并删除 release。

升级

helm upgrade [RELEASE_NAME] [CHART] --install

使用--install可以在 release 不存在时直接执行安装，实现幂等的升级/安装流程。

版本升级注意事项

• 升级到 5.0.0：移除了policy/v1beta1PDB 与PodSecurityPolicy，要求 Kubernetes >= 1.21。
• 升级到 4.2.0：存活探针与就绪探针可通过readinessProbe、livenessProbe两个 values 完全自定义，之前的取值保留为默认值（默认使用 HTTPS 访问/healthz，initialDelaySeconds: 30、timeoutSeconds: 5，见 values.yaml）。
• 升级到 4.0.0：容器安全上下文改为通过securityContext配置，原runAsUser变量弃用，需改用securityContext.runAsUser；同时安全上下文默认启用seccompProfile为RuntimeDefault。
• 升级到 3.0.0：因 Deployment 标签发生变化，升级需要执行helm upgrade --force以重建 Deployment。

关键配置项总览

以下配置均定义在 values.yaml 中，可通过自定义 values 文件覆盖：

从 deployment.yaml 可以看到，这些配置会被拼装为 Adapter 的启动参数：--secure-port、--prometheus-url、--metrics-relist-interval、--v、--config=/etc/adapter/config.yaml，以及可选的--tls-cert-file/--tls-private-key-file。prometheus.url与port、path会被拼接成最终的 Prometheus 端点地址。

配置 Prometheus 服务端点

使用该 Chart 前，必须确保prometheus.url和prometheus.port指向正确的 Prometheus 服务端点。默认值假设 Prometheus 以 HTTP 方式部署在prometheus.default命名空间：

prometheus: url: http://prometheus.default.svc port: 9090 path: ""

如果你的 Prometheus 部署在别的命名空间（例如与 Adapter 同命名空间），可改为：

prometheus: url: http://prometheus.monitoring.svc port: 9090

HTTPS 场景：如果 Prometheus 通过 HTTPS 暴露，则必须将宿主机的 CA 证书包挂载进容器，方式是利用extraVolumes与extraVolumeMounts（对应 values.yaml 中的注释示例）：

extraVolumes: - name: ssl-certs hostPath: path: /etc/ssl/certs/ca-bundle.crt type: File extraVolumeMounts: - name: ssl-certs mountPath: /etc/ssl/certs/ca-certificates.crt readOnly: true

否则 Adapter 在向 HTTPS Prometheus 发起请求时会因无法校验 CA 而失败。

Adapter 规则：三类 Metrics API

Chart 附带一套默认规则（rules.default: true），但默认规则可能拉取过多指标或映射不符合你的需求，因此官方建议通过rules.custom提供自定义规则列表。规则的具体格式遵循 Prometheus Adapter 官方配置文档（该格式同样适用于本仓库中的示例）。

从 configmap.yaml 的实现可以看出规则的落地方式：

• rules.default或rules.custom非空时，生成 ConfigMap 的config.yaml中rules:段（custom 规则通过toYaml直接并入）；
• rules.external非空时，生成externalRules:段；
• rules.resource非空时，生成resourceRules:段；
• rules.existing指定一个已存在的 ConfigMap 名称时，则完全跳过生成，Deployment 直接挂载该 ConfigMap（见 deployment.yaml），此时default/custom/external/resource全部被覆盖。

规则配置中的<<.Resource>>、<<.Series>>、<<.LabelMatchers>>、<<.GroupBy>>是 Prometheus Adapter 的模板占位符，在运行时会被替换为实际的资源名、指标序列、标签匹配器和分组键。

自定义指标（Custom Metrics）

启用该选项后，自定义指标会在/apis/custom.metrics.k8s.io/v1beta1提供服务。当rules.default为 true 时默认启用，也可通过填充rules.custom自定义：

rules: custom: - seriesQuery: '{__name__=~"^some_metric_count$"}' resources: template: <<.Resource>> name: matches: "" as: "my_custom_metric" metricsQuery: sum(<<.Series>>{<<.LabelMatchers>>}) by (<<.GroupBy>>)

对应地，模板 custom-metrics-apiservice.yaml 会在rules.default或rules.custom满足时创建名为v1beta1.custom.metrics.k8s.io的 APIService（优先级groupPriorityMinimum: 100），并把服务指向本 Chart 的 Service。同时 custom-metrics-cluster-role.yaml 会创建针对custom.metrics.k8s.io组的 ClusterRole，verbs 为["*"]，资源范围由rbac.customMetrics.resources（默认["*"]）控制。

外部指标（External Metrics）

启用该选项后，外部指标会在/apis/external.metrics.k8s.io/v1beta1提供服务。通过填充rules.external启用：

rules: external: - seriesQuery: '{__name__=~"^some_metric_count$"}' resources: template: <<.Resource>> name: matches: "" as: "my_external_metric" metricsQuery: sum(<<.Series>>{<<.LabelMatchers>>}) by (<<.GroupBy>>)

外部指标适合那些不属于任何 Namespace/Pod 的指标（例如集群外的服务或云厂商指标），HPA 使用external类型引用。模板 external-metrics-apiservice.yaml 会在rules.external非空时创建名为v1beta1.external.metrics.k8s.io的 APIService。

资源指标（Resource Metrics）

启用该选项后，资源指标会在/apis/metrics.k8s.io/v1beta1提供服务。资源指标允许 Pod 的 CPU 和内存指标被 HPA 使用，同时也支持kubectl top命令。通过填充rules.resource启用，以下为完整示例：

rules: resource: cpu: containerQuery: | sum by (<<.GroupBy>>) ( rate(container_cpu_usage_seconds_total{container!="",<<.LabelMatchers>>}[3m]) ) nodeQuery: | sum by (<<.GroupBy>>) ( rate(node_cpu_seconds_total{mode!="idle",mode!="iowait",mode!="steal",<<.LabelMatchers>>}[3m]) ) resources: overrides: node: resource: node namespace: resource: namespace pod: resource: pod containerLabel: container memory: containerQuery: | round(sum by (<<.GroupBy>>) ( avg_over_time(container_memory_working_set_bytes{container!="",<<.LabelMatchers>>}[3m]) )) nodeQuery: | round(sum by (<<.GroupBy>>) ( avg_over_time(node_memory_MemTotal_bytes{<<.LabelMatchers>>}[3m]) - avg_over_time(node_memory_MemAvailable_bytes{<<.LabelMatchers>>}[3m]) )) resources: overrides: node: resource: node namespace: resource: namespace pod: resource: pod containerLabel: container window: 3m

注意这里的containerQuery使用rate()计算 CPU 使用率、使用avg_over_time()计算内存工作集，nodeQuery则对应节点级别数据，window: 3m定义计算窗口。模板 resource-metrics-apiservice.yaml 会在rules.resource非空时创建名为v1beta1.metrics.k8s.io的 APIService。

重要提示：一旦设置了rules.resource，Chart 会同时部署资源指标 API 服务，功能与 metrics-server 相同，因此二者不能在同一集群中同时部署。

使用已存在的规则 ConfigMap

如果规则维护在别处，可以通过rules.existing指定 ConfigMap 名称，直接复用：

rules: existing: my-adapter-config

此时 Chart 不再生成 ConfigMap，Deployment 直接挂载指定名称的 ConfigMap（见 deployment.yaml），rules.default、rules.custom、rules.external、rules.resource均被忽略。

让 HPA 使用自定义指标

完成上述配置并部署后，即可在 HPA 中引用自定义指标。参见 Kubernetes 官方 HPA 演练文档中关于自定义指标的部分（custom metrics 与 multiple metrics 章节）。一个典型的使用形态：

apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: my-app-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: my-app minReplicas: 2 maxReplicas: 10 metrics: - type: Pods pods: metric: name: my_custom_metric target: type: AverageValue averageValue: "100"

HPA 会通过custom.metrics.k8s.ioAPI 查询my_custom_metric（对应rules.custom中name.as定义的名称），依据平均值目标自动扩缩容。若指标不属于 Pod/Namespace 维度，则使用type: External配合rules.external中定义的指标名。

安全与证书：TLS 与 cert-manager

Adapter 的 APIService 与 kube-apiserver 之间需要 TLS。Chart 提供两种证书方案：

方式一：tls.enable（自带证书）

tls: enable: true ca: |- # 签发 APIService 的公共 CA 证书内容 key: |- # APIService 的私钥 certificate: |- # APIService 的公钥

启用后，模板会把ca内容 base64 编码注入 APIService 的caBundle（见 custom-metrics-apiservice.yaml），证书/密钥以 Secret 挂载到/var/run/serving-cert（见 deployment.yaml），并通过--tls-cert-file/--tls-private-key-file参数启用。

方式二：certManager.enabled（cert-manager 自动签发）

certManager: enabled: true caCertDuration: 43800h0m0s # CA 证书有效期，默认 5 年 certDuration: 8760h0m0s # 服务证书有效期，默认 1 年

启用后，模板 certmanager.yaml 会依次创建：自签 Issuer → 根 CA Certificate（*-root-cert）→ 基于 CA 的 Issuer → 服务证书 Certificate，并自动为 APIService 注入cert-manager.io/inject-ca-from注解实现 CA 自动注入。

未启用任何 TLS 时，APIService 会设置insecureSkipTLSVerify: true，适合快速试用环境。

从源码看部署细节

Deployment 组装

deployment.yaml 展示了 Chart 的完整部署逻辑：容器镜像默认取image.repository+ ChartappVersion（v0.12.0），支持image.tag覆盖；Pod 默认启用automountServiceAccountToken；podSecurityContext.fsGroup: 10001用于满足 Kubernetes 1.21 非 root 部署的文件组要求；securityContext默认设置allowPrivilegeEscalation: false、runAsNonRoot: true、runAsUser: 10001、readOnlyRootFilesystem: true与seccompProfile: RuntimeDefault。ConfigMap 变更会通过checksum/config注解触发 Pod 滚动更新。

Service 与探针

service.yaml 创建 ClusterIP 服务，端口 443 转发到容器 https 端口，并支持通过service.ipDualStack启用 IPv4/IPv6 双栈。探针（livenessProbe/readinessProbe/startupProbe）均可通过 values 覆盖，其中startupProbe默认空，官方注释建议在 Adapter 启动较慢（例如需要轮询大量 API 版本）时配置。

命名与标签

_helpers.tpl 定义了资源命名规则（fullname截断至 63 字符）、标签体系（app.kubernetes.io/component: metrics、app.kubernetes.io/part-of、app.kubernetes.io/version等）以及namespaceOverride对发布命名空间的覆盖能力，便于在组合 Chart 中多命名空间部署。

典型配置示例：完整 values

综合以上内容，一个生产可用的配置模板如下：

replicas: 2 prometheus: url: http://prometheus.monitoring.svc port: 9090 rules: default: false custom: - seriesQuery: '{__name__=~"^http_requests_total$"}' resources: overrides: namespace: {resource: namespace} pod: {resource: pod} name: matches: "^(.*)_total$" as: "${1}_per_second" metricsQuery: sum(rate(<<.Series>>{<<.LabelMatchers>>}[1m])) by (<<.GroupBy>>) resources: requests: cpu: 100m memory: 128Mi limits: cpu: 100m memory: 128Mi podDisruptionBudget: enabled: true minAvailable: 1

将以上内容保存为values-custom.yaml后执行：

helm install my-adapter oci://ghcr.io/prometheus-community/charts/prometheus-adapter -f values-custom.yaml

验证部署

部署后可进行以下验证：

1. 查看 Pod 状态与日志：

kubectl get pods -l app.kubernetes.io/name=prometheus-adapter kubectl logs -l app.kubernetes.io/name=prometheus-adapter

2. 确认 APIService 注册成功：

kubectl get apiservice | grep metrics.k8s.io

3. 验证自定义指标可查询：

kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1 kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/default/pods/*/my_custom_metric"

4. 若启用资源指标，可执行kubectl top nodes/kubectl top pods验证。

总结

Prometheus Adapter Helm Chart 将复杂的 Metrics API 桥接工作封装为一键部署：通过rules.custom、rules.external、rules.resource三类规则分别驱动 Custom Metrics、External Metrics 与 Resource Metrics 三类 API，配合 APIService、RBAC、探针、PDB、TLS/cert-manager 等完整的周边资源，使基于 Prometheus 业务指标的 HPA 弹性伸缩可以快速落地。核心要点是：正确配置prometheus.url/port端点、按需编写规则（推荐rules.custom而非全量默认规则）、根据集群情况选择 TLS 方案，并牢记资源指标与 metrics-server 不可同时部署。