CloudNativePG Helm Chart

CloudNativePG Helm Chart#

The cloudnative-pg/charts repository provides a cluster Helm chart that deploys and configures CloudNativePG Cluster resources and associated objects — including backups, monitoring, image catalogs, and PgBouncer Pooler resources — via a single values.yaml interface.

Key source files:

File	Purpose
`charts/cluster/values.yaml`	All configurable values with inline documentation
`charts/cluster/templates/`	34 templates (cluster, poolers, backups, monitoring, etc.)
`charts/cluster/templates/pooler.yaml`	Renders `Pooler` CRD objects
`charts/cluster/templates/podmonitor-pooler.yaml`	Renders `PodMonitor` objects for pooler metrics

The chart supports three cluster modes — standalone (default), replica, and recovery — and three database types: postgresql, postgis, and timescaledb .

Pooler Configuration via the Chart#

Poolers are declared as a list under .Values.poolers[]. Multiple poolers can be defined (e.g., one for rw, one for ro) .

The pooler.yaml template iterates over .Values.poolers and renders one Pooler CR per entry. The fields it exposes are:

Chart value	CRD field	Notes
`instances`	`spec.instances`	Number of PgBouncer replicas
`type`	`spec.type`	`rw` (default), `ro`, or `r`
`poolMode`	`spec.pgbouncer.poolMode`	`session` (default) or `transaction`
`authQuerySecret`	`spec.pgbouncer.authQuerySecret`	Deprecated in the CRD
`authQuery`	`spec.pgbouncer.authQuery`	Deprecated in the CRD
`parameters`	`spec.pgbouncer.parameters`	Arbitrary PgBouncer config knobs
`pg_hba`	`spec.pgbouncer.pg_hba`	Additional `pg_hba.conf` lines
`template`	`spec.template`	Full pod template pass-through

The pooler template field is rendered with a raw toYaml pass-through , meaning arbitrary pod spec overrides (resources, image, sidecars, etc.) can be injected there even though they have no dedicated chart value.

Pooler monitoring is handled by podmonitor-pooler.yaml, which creates a PodMonitor when poolers[].monitoring.enabled and poolers[].monitoring.podMonitor.enabled are both true . It supports relabelings and metricRelabelings per pooler .

Gaps: Pooler CRD Fields Not Exposed by the Chart#

The authoritative Pooler CRD type is defined in api/v1/pooler_types.go. Several PoolerSpec and PgBouncerSpec fields have no corresponding chart value and cannot be set without a post-render hook or a raw template: override.

`PoolerSpec` gaps#

CRD field	Type	Description
`deploymentStrategy`	`appsv1.DeploymentStrategy`	Controls rollout strategy for the PgBouncer Deployment
`serviceTemplate`	`ServiceTemplateSpec`	Customizes the Service created for the pooler (metadata + `ServiceSpec`)
`serviceAccountName`	`string`	Use an existing ServiceAccount instead of auto-creating one; immutable after creation
`monitoring` (CRD-level)	`PoolerMonitoringConfiguration`	Includes `enablePodMonitor`, relabeling configs, and `tls.enabled` for the metrics endpoint

Note: the CRD's monitoring.enablePodMonitor and the chart's podmonitor-pooler.yaml are parallel mechanisms. The chart creates the PodMonitor object itself rather than delegating to the operator via spec.monitoring.enablePodMonitor .

`PgBouncerSpec` gaps#

CRD field	Type	Description
`serverTLSSecret`	`LocalObjectReference`	TLS key/cert for PgBouncer → PostgreSQL authentication
`serverCASecret`	`LocalObjectReference`	Root CA for validating PostgreSQL server certificates
`clientCASecret`	`LocalObjectReference`	Root CA for validating client certificates
`clientTLSSecret`	`LocalObjectReference`	TLS key/cert for accepting client connections
`paused`	`*bool`	Pause all new client connections (`PAUSE`/`RESUME`)
`image`	`string`	Direct PgBouncer container image override
`imageCatalogRef`	`ImageCatalogComponentRef`	Reference to an ImageCatalog entry; mutually exclusive with `image`

Workaround: The template pass-through (chart value poolers[].template) covers pod-level concerns (image, resources, env vars), but the serviceTemplate, serviceAccountName, deploymentStrategy, and all TLS secret references require a Helm post-renderer or a separately managed Pooler manifest.

Other Notable Chart Features#

Backups (backups.*): ScheduledBackup and WAL archiving configuration for S3, Azure, and GCS .
Monitoring (cluster.monitoring.*): PodMonitor, PrometheusRule, custom metrics queries, and TLS for the metrics endpoint .
Declarative databases & roles (databases[], cluster.roles[]): Managed via CNPG's declarative API .
Replication slots (cluster.replicationSlots): HA replication slots with optional logical decoding sync; requires CNPG 1.27+ and PostgreSQL 17+ for native failover slots .
Console StatefulSet (cluster.console.enabled): Runs long-running commands (e.g., CREATE INDEX) against the cluster .