Prometheus Adapter Helm Chart 深度指南为 Kubernetes HPA 接入 Prometheus 自定义指标【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend导读本指南围绕仓库中 Deepgram Nova-3 自托管部署所使用的 prometheus-adapter Helm Chart版本 4.14.2适配 prometheus-adapter v0.12.0展开系统讲解如何将 Prometheus 指标桥接为 Kubernetes 的 Custom / External / Resource Metrics API从而让 Horizontal Pod Autoscaler 依据业务自定义指标如 STT 流式请求数、TTS 批处理负载自动扩缩容。读完本文你将掌握该 Chart 的安装、卸载、升级与全部核心配置项并能结合仓库中真实的自托管 HPA 配置编写出自己的 adapter 规则与 HPA 声明。Prometheus Adapter 在 Kubernetes 弹性伸缩中的定位在 Kubernetes 中kubectl top、HPA 等组件消费的是三类标准的 Metrics APIResource Metrics API/apis/metrics.k8s.io/v1beta1提供 Pod CPU / 内存这类资源指标通常由metrics-server提供Custom Metrics API/apis/custom.metrics.k8s.io/v1beta1提供与特定对象Pod、Namespace 等绑定的自定义指标External Metrics API/apis/external.metrics.k8s.io/v1beta1提供不与具体 Kubernetes 对象绑定的外部指标如队列长度、GPU 负载、外部服务指标。metrics-server只能解决“资源指标”这一类场景。当 HPA 需要依据业务指标比如当前活跃的语音转写请求数扩容时就需要一个指标桥接层把 Prometheus 中采集到的序列翻译成上述 API 能消费的格式——这正是 Prometheus Adapterkubernetes-sigs/prometheus-adapter的职责。在本仓库中该 Chart 以依赖子图的形式被 Deepgram Nova-3 自托管 Helm 包引用见 nova-3/Chart.yaml其存在价值是配合scaling.auto.enabled为 Deepgram 的 API / Engine 服务提供基于业务指标的自动扩缩容。Chart 版本与前置条件Chart 元数据定义在 Chart.yamlChart 版本4.14.2对应应用版本appVersionv0.12.0镜像仓库为registry.k8s.io/prometheus-adapter/prometheus-adaptervalues.yaml关键词hpa、metrics、prometheus、adapter前置条件Kubernetes 1.14。Chart 通过两种发行方式分发OCI 制品oci://ghcr.io/prometheus-community/charts/prometheus-adapter传统 Helm 仓库https://prometheus-community.github.io/helm-chartschart 名为prometheus-adapter安装、卸载与升级安装helm install [RELEASE_NAME] oci://ghcr.io/prometheus-community/charts/prometheus-adapter安装前可先查看默认值与全部可配置项helm show values oci://ghcr.io/prometheus-community/charts/prometheus-adapter在 Deepgram Nova-3 自托管场景中该 Chart 不是独立安装的而是作为依赖随主 Chart 一起渲染。主 Chart 的 README 明确指出当scaling.auto.enabled为 true 时Chart 默认会安装 Prometheus Adapter若你希望在自己的集群中自行管理 adapter可通过prometheus-adapter.includeDependency: false强制不随主 Chart 安装。仓库的开发环境配置 dev_omi_values.yaml 中即给出了覆盖示例prometheus-adapter: includeDependency: false prometheus: url: http://dg-prometheus-stack-prometheus.{{ .Release.Namespace }}.svc rules: default: false external: - name: as: engine_active_requests_stt_streaming seriesQuery: engine_active_requests{kindstream} metricsQuery: avg(engine_active_requests{kindstream}) resources: overrides: namespace: { resource: namespace } pod: { resource: pod } service: { resource: service }卸载helm uninstall [RELEASE_NAME]该命令会移除 Chart 创建的所有 Kubernetes 组件并删除对应 release。升级helm upgrade [RELEASE_NAME] [CHART] --install注意升级到3.0.0时由于 Deployment 标签发生变化需要helm upgrade --force强制重建 Deployment。主要升级变更4.2.0readinessProbe与livenessProbe完全可配置化旧值保留为默认值4.0.0容器安全上下文通过新的securityContext变量配置默认值沿用旧设置原runAsUser变量废弃改用securityContext.runAsUser同时默认启用seccompProfile类型为RuntimeDefault3.0.0Deployment 标签变更需--force升级。核心配置项解析完整配置项可查看 values.yaml以下为关键配置的实战说明。镜像与基本运行参数image: repository: registry.k8s.io/prometheus-adapter/prometheus-adapter tag: # 为空时使用 Chart.yaml 的 appVersion (v0.12.0) pullPolicy: IfNotPresent pullSecrets: [] logLevel: 4 # 对应启动参数 --v metricsRelistInterval: 1m # 对应 --metrics-relist-interval listenPort: 6443 # 对应 --secure-port replicas: 1这些值在 deployment.yaml 中被映射为容器启动参数--secure-port、--prometheus-url、--metrics-relist-interval、--v、--config/etc/adapter/config.yaml。metricsRelistInterval控制 adapter 重新发现 Prometheus 指标序列series的频率值越小发现越及时但会增加 Prometheus 查询压力。Prometheus 服务端点prometheus: url: http://prometheus.default.svc port: 9090 path: url支持模板渲染deployment 中通过tpl处理见 deployment.yaml因此可以写成http://dg-prometheus-stack-prometheus.{{ .Release.Namespace }}.svc这类带命名空间的动态地址port默认9090Prometheus 默认 HTTP 端口若 Prometheus 通过 HTTPS 暴露则必须将宿主 CA Bundle 通过extraVolumesextraVolumeMounts挂载进容器否则 TLS 校验会失败。安全上下文与 RBACpodSecurityContext: fsGroup: 10001 securityContext: allowPrivilegeEscalation: false capabilities: drop: [ALL] readOnlyRootFilesystem: true runAsNonRoot: true runAsUser: 10001 seccompProfile: type: RuntimeDefault rbac: create: true useAuthReaderClusterRole: false externalMetrics: resources: [*] customMetrics: resources: [*]readOnlyRootFilesystem: true配合 Deployment 中的/tmpemptyDir 挂载deployment.yaml保证只读根文件系统下可写临时证书目录rbac.create控制是否创建 Custom/External/Resource Metrics 对应的 ClusterRole、ClusterRoleBinding 与 HPA 绑定的授权角色useAuthReaderClusterRole: true时使用集群级 auth-reader ClusterRole而非命名空间级 RoleBinding。探针与滚动策略livenessProbe: httpGet: path: /healthz port: https scheme: HTTPS initialDelaySeconds: 30 timeoutSeconds: 5 readinessProbe: httpGet: path: /healthz port: https scheme: HTTPS initialDelaySeconds: 30 timeoutSeconds: 5 startupProbe: {} # 启动慢如集群中 API 版本轮询较多时建议配置 strategy: type: RollingUpdate rollingUpdate: maxUnavailable: 25% maxSurge: 25% podDisruptionBudget: enabled: false minAvailable: maxUnavailable: 1注意探针走 HTTPS因为 adapter 以 TLS 提供服务--secure-port6443。服务与 TLSservice: annotations: {} port: 443 type: ClusterIP tls: enable: false ca: |- # 签发 APIService 的公共 CA key: |- # APIService 私钥 certificate: |- # APIService 公钥 certManager: enabled: false caCertDuration: 43800h0m0s certDuration: 8760h0m0stls.enable: true时adapter 使用--tls-cert-file/var/run/serving-cert/tls.crt与--tls-private-key-file/var/run/serving-cert/tls.keydeployment.yaml证书来自同名 Secret也可启用certManager由 cert-manager 自动签发短期证书默认根 CA 5 年、叶子证书 1 年未启用任何 TLS 时custom-metrics-apiservice.yaml 会设置insecureSkipTLSVerify: true。其他常用项env: [] # 附加环境变量支持 secretKeyRef / configMapKeyRef extraArguments: [] # 附加启动参数如 --tls-private-key-file extraVolumes: [] # 附加卷如挂载 CA Bundle extraVolumeMounts: [] # 附加卷挂载 extraContainers: [] # sidecar 容器 extraManifests: [] # 附加自定义 manifest hostNetwork: enabled: false # 备用 overlay 网络导致 API server 无法访问 adapter 时开启 nodeSelector: {} affinity: {} topologySpreadConstraints: [] tolerations: [] priorityClassName: Adapter 规则打通三种 Metrics APIChart 将rules渲染进 ConfigMapconfig.yaml该 ConfigMap 挂载到/etc/adapter/deployment.yaml并作为--config/etc/adapter/config.yaml加载。渲染逻辑见 configmap.yaml。默认规则rules.defaultrules.default: true默认值会启用一套开箱即用的规则将常见的container_*系列与通用命名空间指标映射为 custom metrics。默认规则的处理逻辑源码级container_*_seconds_total→ 以rate(…[5m])聚合container_*_total→ 同样以rate(…[5m])聚合其余container_*→ 直接sum(...) by (.GroupBy)非容器指标按.*_total、.*_seconds_total后缀分别做速率/直接求和处理。这些规则可能拉取过多指标或映射不符合业务需求因此文档建议通过rules.custom提供自定义规则列表格式参考 prometheus-adapter 官方 config 文档。自定义指标Custom Metrics启用rules.custom后自定义指标会在/apis/custom.metrics.k8s.io/v1beta1提供。示例rules: custom: - seriesQuery: {__name__~^some_metric_count$} resources: template: .Resource name: matches: as: my_custom_metric metricsQuery: sum(.Series{.LabelMatchers}) by (.GroupBy)字段语义seriesQuery指定该规则适用的 Prometheus 指标序列resources指定 Kubernetes 资源到指标标签的映射overrides显式声明或template自动匹配.Resourcename.matches/name.as将原始指标名改写为对外暴露的指标名可用正则捕获组metricsQuery最终执行在 Prometheus 上的查询模板.Series、.LabelMatchers、.GroupBy是 adapter 注入的模板变量。外部指标External Metrics启用rules.external后外部指标在/apis/external.metrics.k8s.io/v1beta1提供规则结构与 custom 相同。Deepgram Nova-3 生产/开发配置正是通过 external 规则暴露engine_active_requests_stt_streamingSTT 流式活跃请求数、engine_active_requests_stt_batch、engine_active_requests_tts_batch等指标见 dev_omi_values.yaml 与 prod_omi_values.yaml。Chart 自带的 CI 冒烟测试 external-rules-values.yaml 展示了最简 external 规则写法。资源指标Resource Metrics启用rules.resource后资源指标在/apis/metrics.k8s.io/v1beta1提供使 Pod CPU/内存指标可用于 HPA 与kubectl top。Chart 默认模板values.yaml 中被注释如下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注意一旦设置了rules.resourceChart 会同时部署 resource metrics API Service其功能与metrics-server等价因此二者不能在同一集群中共存。使用已有规则rules.existingrules: existing: my-pre-generated-rules-configmap指定已有 ConfigMap 名称后adapter 将直接使用该 ConfigMap覆盖 default/custom/external/resource 全部条目且 Chart 不再渲染默认 ConfigMap见 configmap.yaml 与 deployment.yaml 的rules.existing | default (fullname)逻辑。与 HPA 的实际联动以 Deepgram 自托管为例外部指标定义好后HPA 即可通过type: External引用。仓库的 engine.hpa.yaml 展示了完整联动apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: {{ .Values.engine.namePrefix }}-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: {{ .Values.engine.namePrefix }} minReplicas: {{ .Values.scaling.auto.engine.minReplicas }} maxReplicas: {{ .Values.scaling.auto.engine.maxReplicas }} metrics: - type: External external: metric: name: engine_active_requests_stt_batch target: type: Value value: {{ .Values.scaling.auto.engine.metrics.speechToText.batch.requestsPerPod }} - type: External external: metric: name: engine_active_requests_stt_streaming target: type: Value value: {{ .Values.scaling.auto.engine.metrics.speechToText.streaming.requestsPerPod }} - type: External external: metric: name: engine_active_requests_tts_batch target: type: Value value: {{ .Values.scaling.auto.engine.metrics.textToSpeech.batch.requestsPerPod }} behavior: {{- toYaml .Values.scaling.auto.engine.behavior | nindent 4 }}可见 adapter 的rules.external中name.as定义的指标名与 HPA 中metric.name一一对应。HPA 依据“活跃请求数 ÷ requestsPerPod”的比值驱动副本数变化。API 服务的 HPAapi.hpa.yaml则引用engine_to_api_pod_ratio外部指标实现“引擎副本数到 API 副本数”的联动缩放。常见问题与排查要点HPA 报unable to fetch metrics优先检查prometheus.url/port是否指向正确的 Prometheus Service并用curl http://prometheus-svc:9090/api/v1/query?querymetricsQuery验证查询本身可执行。指标暴露为[window]而非数值通常是 metricsQuery 聚合缺失未by (.GroupBy)或指标标签与resources.overrides不匹配。HTTPS Prometheus 报证书错误通过extraVolumes/extraVolumeMounts将 CA Bundle 挂载进容器。与 metrics-server 冲突不要同时启用rules.resource与 metrics-server。升级到 3.0.0 后 Deployment 未更新标签变化需要helm upgrade --force。namespaceOverride / 多命名空间部署通过namespaceOverride覆盖 release namespace配合customAnnotations/customLabels统一标记资源。结语Prometheus Adapter 是连接 Prometheus 指标世界与 Kubernetes 原生扩缩容机制的关键桥梁。通过本仓库中随 Deepgram Nova-3 自托管交付的该 Chart你可以快速获得三类 Metrics API 的完整能力用rules.custom暴露业务自定义指标、用rules.external暴露跨对象的外部指标、用rules.resource替代 metrics-server。再配合autoscaling/v2的 HPA 声明与behavior缩放策略即可构建出像 Deepgram Engine 那样按活跃请求数精确驱动的生产级自动扩缩容体系。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考