Helm 部署 Prometheus Postgres Exporter 全指南：从数据源配置到自定义查询指标

本篇技术指南以 charts 仓库中 stable/prometheus-postgres-exporter 这一 Helm Chart 为核心，系统讲解如何在 Kubernetes 集群中通过 Helm 一键部署 postgres_exporter，将 PostgreSQL 的运行指标（连接数、表读写、复制延迟、语句性能等）暴露给 Prometheus 抓取。读完本文，你将掌握该 Chart 的全部配置参数、数据源连接方式、自定义 SQL 查询指标、与 Prometheus Operator 的 ServiceMonitor 集成，以及从模板源码层面理解其实现原理与部署细节。

一、Chart 简介与适用场景

postgres_exporter 是 Prometheus 官方生态中最常用的 PostgreSQL 指标导出器，该 Chart 负责在 Kubernetes 上以 Deployment 形式启动它，并封装了 Service、ConfigMap、Secret、ServiceAccount、RBAC 乃至 ServiceMonitor 等配套资源。其核心价值在于：

• 一键部署 exporter 并自动生成连接配置，免去手工编写 YAML 的繁琐；
• 通过 values.yaml 集中管理数据源地址、账号密码、查询配置等所有可调参数；
• 内置多组 PostgreSQL 官方推荐查询（复制延迟、表统计、IO 统计、数据库大小、语句性能），开箱即用；
• 可直接对接 Prometheus Operator 的 ServiceMonitor，实现自动化采集。

从 Chart.yaml 可以看到该 Chart 的元信息：名称prometheus-postgres-exporter、版本1.3.1、appVersion: 0.8.0（对应 postgres_exporter 镜像wrouesnel/postgres_exporter:v0.8.0）。需要说明的是，该 Chart 已在 Chart.yaml 中标记deprecated: true，官方维护已迁移至 prometheus-community 的 helm-charts 仓库，但作为经典实现，其配置逻辑与模板设计仍极具参考价值，本指南以当前仓库内的实际代码为准。

二、快速开始：一行命令部署

最简安装方式（TL;DR）：

$ helm install stable/prometheus-postgres-exporter

执行后即会在集群默认配置下创建 exporter Deployment 及其关联资源。默认情况下，exporter 会使用 values.yaml 中的默认数据源配置（主机为空、用户postgres、密码somepassword、端口5432、sslmode=disable），因此生产环境必须先修改数据源配置（见下文第四节），否则采集的是默认示例连接。

三、安装与卸载

以发布名my-release安装：

$ helm install --name my-release stable/prometheus-postgres-exporter

注意：--name是 Helm 2 的语法，若使用 Helm 3，请改用helm install my-release stable/prometheus-postgres-exporter。

卸载并删除发布：

$ helm delete my-release

该命令会移除 Chart 关联的所有 Kubernetes 组件（Deployment、Service、ConfigMap、Secret、RBAC 等）并删除该发布记录。

安装完成后，NOTES.txt 会根据service.type输出访问入口提示：

• ClusterIP：通过kubectl port-forward <pod> 8080:80在本机访问http://127.0.0.1:8080；
• NodePort：通过$NODE_IP:$NODE_PORT访问；
• LoadBalancer：通过$SERVICE_IP访问，等待 LB IP 就绪可执行kubectl get svc -w <release>-prometheus-postgres-exporter。

四、配置参数详解

4.1 参数总表

以下参数继承自 README.md 并对照 values.yaml 校准默认值：

说明：README 参数表中imageTag/imagePullPolicy为旧版扁平命名，当前 values.yaml 已统一为嵌套结构image.repository、image.tag、image.pullPolicy，且镜像 tag 已从表中记录的v0.5.1升级为v0.8.0，配置时以 values.yaml 结构为准。

4.2 通过 --set 指定参数

$ helm install --name my-release \ --set serviceAccount.name=postgres \ stable/prometheus-postgres-exporter

4.3 通过 values 文件指定参数

$ helm install --name my-release -f values.yaml stable/prometheus-postgres-exporter

-f可叠加多个文件，后指定的文件优先级更高，适合将环境差异（开发/生产）拆分为不同 values 文件管理。

五、连接 PostgreSQL 数据源：两种配置方式

5.1 方式一：结构化字段 config.datasource

values.yaml 提供结构化配置：

config: datasource: host: my-postgres user: postgres password: somepassword # passwordSecret: # name: db-secret # key: password port: "5432" database: appdb sslmode: disable

模板会将其组装为连接 URI。在 _helpers.tpl 中定义了data_source_uri模板：

host:port/database?sslmode=ssl

最终在 deployment.yaml 中转换为三个环境变量注入容器：

• DATA_SOURCE_URI：host:port/database?sslmode=...
• DATA_SOURCE_USER：数据库用户名
• DATA_SOURCE_PASS：数据库密码

其中密码优先从passwordSecret指定的 Secret 中读取（secretKeyRef），否则由 secrets.yaml 自动创建名为<release>-prometheus-postgres-exporter的 Secret，将config.datasource.password经b64enc编码存入data_source_password键。

源码校验：若同时定义了passwordSecret与password，deployment.yaml 顶部会直接执行fail中断渲染并报错ERROR: only one of .Values.config.datasource.passwordSecret and .Values.config.datasource.password must be defined，强制二选一，避免歧义。

5.2 方式二：完整连接串 config.datasourceSecret

当数据源较多或希望以标准 URL 形式集中管理时，可使用datasourceSecret：

config: datasourceSecret: name: pg-conn key: connection

Secret 的值须为连接串格式：

postgresql://login:password@hostname:port/dbname?sslmode=disable

支持用逗号分隔多个连接串来配置多个 PostgreSQL 数据库。此时 deployment.yaml 不再使用结构化字段，而是通过secretKeyRef将 Secret 的值注入单一环境变量DATA_SOURCE_NAME。这也是 postgres_exporter 官方支持多数据源的标准方式。

六、自定义查询指标：config.queries 深度解析

6.1 查询配置文件如何生效

config.queries是一段 YAML 字符串，它被写入 configmap.yaml 生成的 ConfigMap 中（键名为config.yaml），并通过卷挂载到容器内/etc/config.yaml（见 deployment.yaml 的volumeMounts，使用subPath: config.yaml精确挂载单文件）。

容器启动时携带参数：

--extend.query-path=/etc/config.yaml

即告诉 postgres_exporter 额外加载此查询文件，生成自定义指标。此外，ConfigMap 内容变化会通过checksum/config注解（值为sha256sum）触发 Pod 滚动更新，保证查询配置修改后无需手动重启。

6.2 内置默认查询集

values.yaml 内置了从 postgres_exporter 官方 queries.yaml 提取的六组查询，覆盖最常用的监控维度：

① pg_replication：复制延迟

pg_replication: query: "SELECT EXTRACT(EPOCH FROM (now() - pg_last_xact_replay_timestamp())) as lag" master: true metrics: - lag: usage: "GAUGE" description: "Replication lag behind master in seconds"

master: true表示仅主库执行（用于备库复制延迟告警）。

② pg_postmaster：实例启动时间

pg_postmaster: query: "SELECT pg_postmaster_start_time as start_time_seconds from pg_postmaster_start_time()" master: true metrics: - start_time_seconds: usage: "GAUGE" description: "Time at which postmaster started"

③ pg_stat_user_tables：用户表统计（含 vacuum/analyze）

查询返回seq_scan、seq_tup_read、idx_scan、idx_tup_fetch、n_tup_ins/upd/del/hot_upd、n_live_tup、n_dead_tup、n_mod_since_analyze以及last_vacuum、last_autovacuum、last_analyze、last_autoanalyze和vacuum_count、autovacuum_count、analyze_count、autoanalyze_count。其中datname、schemaname、relname作为LABEL维度，其余计数指标按 COUNTER/GAUGE 语义暴露。

④ pg_statio_user_tables：表 IO 统计

涵盖heap_blks_read/hit、idx_blks_read/hit、toast_blks_read/hit、tidx_blks_read/hit，用于分析缓冲命中率与磁盘 IO。

⑤ pg_database：数据库大小

pg_database: query: "SELECT pg_database.datname, pg_database_size(pg_database.datname) as size FROM pg_database" master: true cache_seconds: 30 metrics: - datname: usage: "LABEL" description: "Name of the database" - size_bytes: usage: "GAUGE" description: "Disk space used by the database"

cache_seconds: 30表示结果缓存 30 秒，避免pg_database_size反复执行带来的开销。

⑥ pg_stat_statements：语句性能分析

依赖pg_stat_statements扩展，输出calls、total_time_seconds、min/max/mean/stddev_time_seconds、rows、共享/本地缓冲命中与读写、临时块读写、块读写耗时等指标，按rolname、datname、queryid打标签。该查询仅当数据库启用pg_stat_statements扩展且有对应权限时才能返回数据。

6.3 自定义查询的写法

用户可按同一格式追加自己的查询块：

config: queries: |- my_custom_metric: query: "SELECT count(*) as total FROM my_table" master: true metrics: - total: usage: "GAUGE" description: "Total rows in my_table"

指标usage支持GAUGE、COUNTER、LABEL三种类型：数值型用GAUGE/COUNTER，用于分组的维度列用LABEL。配置即改即生效（ConfigMap 变更触发滚动更新）。

6.4 指标开关：默认指标与设置指标

• config.disableDefaultMetrics: true：仅采集config.queries中定义的指标，忽略 exporter 内置默认指标，对应启动参数--disable-default-metrics（见 deployment.yaml）。
• config.disableSettingsMetrics: true：禁用设置类指标（如pg_settings_*），对应--disable-settings-metrics，可显著减少指标基数。

七、数据库自动发现

config.autoDiscoverDatabases: true时，exporter 会自动发现实例上的所有数据库并逐一采集，启动参数为--auto-discover-databases；配合config.excludeDatabases排除不需要监控的库（如系统库postgres、template0/1等）：

config: autoDiscoverDatabases: true excludeDatabases: - postgres - template0 - template1

模板会将列表以逗号拼接后通过--exclude-databases参数传入（见 deployment.yaml 第 44-50 行）。

八、与 Prometheus Operator 集成：ServiceMonitor

当集群安装了 Prometheus Operator 且serviceMonitor.enabled: true时，servicemonitor.yaml 会创建monitoring.coreos.com/v1的 ServiceMonitor 资源。模板以Capabilities.APIVersions.Has "monitoring.coreos.com/v1"判断 API 是否可用，避免在不支持时渲染失败。

serviceMonitor: enabled: true namespace: monitoring interval: 30s telemetryPath: /metrics timeout: 10s labels: release: prometheus-operator

对应生成：

• spec.endpoints[].targetPort：指向 Service 端口名http；
• interval/scrapeTimeout：抓取频率与超时；
• path：抓取路径（exporter 默认/metrics）；
• jobLabel：取 fullname；
• namespaceSelector.matchNames：锁定 Release 所在命名空间；
• selector.matchLabels：按app+release标签选中目标 Service。

提示：若你的 Prometheus Operator 通过prometheusSpec.serviceMonitorSelector选择 ServiceMonitor，需通过serviceMonitor.labels打上对应标签（如release: prometheus-operator），否则无法被发现。

九、服务暴露与访问验证

service.yaml 生成的 Service 默认类型ClusterIP，端口80→ 容器9187，端口名http。exporter 健康检查见 deployment.yaml：

• livenessProbe/readinessProbe：均通过httpGet请求/路径、http端口。

部署完成后可验证指标输出：

$ kubectl port-forward svc/my-release-prometheus-postgres-exporter 8080:80 $ curl http://127.0.0.1:8080/metrics

返回体中应包含pg_up 1（连接成功标志）以及上文各查询块生成的指标。若要变更暴露方式，设置service.type: NodePort或LoadBalancer即可。

十、RBAC、ServiceAccount 与安全

role.yaml 在rbac.create: true且rbac.pspEnabled: true时创建 Role，授予对该 Chart 生成的 PodSecurityPolicy 的use权限（PSP 定义见 podsecuritypolicy.yaml，绑定关系见 rolebinding.yaml）。

serviceaccount.yaml 在serviceAccount.create: true时创建专属 ServiceAccount；名称未指定时由 _helpers.tpl 的serviceAccountName模板生成（默认default兜底）。Deployment 通过serviceAccountName引用它。

securityContext可配置 Pod 级安全上下文，例如在 values.yaml 中放开注释启用只读文件系统或指定runAsUser: 65534（nobody）：

securityContext: runAsUser: 65534

十一、调度、资源与扩展

• nodeSelector/affinity/tolerations：将 exporter 固定到特定节点或按亲和性调度；
• resources：显式声明 CPU/内存 requests 与 limits（默认{}不限制，适合 Minikube 等小环境）；
• annotations/podLabels：向 Deployment/Pod 注入自定义注解与标签；
• extraContainers/extraVolumes：以字符串形式追加 sidecar 容器与卷，典型用途是搭配 Google CloudSQL Proxy 等数据库代理，实现经由代理连接云数据库的采集拓扑。

十二、从模板源码看整体部署拓扑

综合各模板文件，一次helm install实际生成的资源链路如下：

1. configmap.yaml：承载config.queries查询定义；
2. secrets.yaml：承载明文配置的数据库密码；
3. deployment.yaml：组装连接环境变量、挂载查询文件、注入启动参数与探针，并做password/passwordSecret互斥校验；
4. service.yaml：暴露9187指标端口；
5. servicemonitor.yaml：对接 Prometheus Operator；
6. serviceaccount.yaml、role.yaml、rolebinding.yaml、podsecuritypolicy.yaml：完成权限与安全策略。

其中连接串拼装逻辑集中在 _helpers.tpl 的data_source_uri定义中，改动连接格式只需维护这一处模板，其余资源通过fullname/name/chart/release/heritage标准标签形成关联，体现了 Helm 模板复用的设计惯例。

十三、弃用说明与迁移提示

如 Chart.yaml 所标注，该 Chart 已deprecated: true且不再维护，官方将其迁移至 prometheus-community 的 helm-charts 仓库。当前仓库内的实现（镜像 tagv0.8.0、appVersion 0.8.0）仍可正常安装使用，迁移到新仓库时，本节所述的config.datasource、config.queries、serviceMonitor等核心配置语义基本保持一致，可平滑对照迁移。若在旧版 Kubernetes 集群使用，请注意 PSP 等资源随集群版本演进可能需要调整。