CloudNativePG Pooler Configuration#

CloudNativePG provides native connection pooling through the Pooler CRD, which deploys a scalable set of PgBouncer pods between applications and a PostgreSQL cluster 1. A Pooler is always namespace-scoped to the same namespace as its target Cluster, and its lifecycle is independent — deleting the cluster does not remove the pooler and vice versa 2.

Prerequisite: PgBouncer version 1.19+ is required because CloudNativePG relies on the auth_dbname feature introduced in that release 3.

Entry points:

• API types: api/v1/pooler_types.go — PoolerSpec, PgBouncerSpec, PoolerStatus
• Helper methods: api/v1/pooler_funcs.go — IsAutomatedIntegration, IsMetricsTLSEnabled, TLS secret resolution
• Admission webhook: internal/webhook/v1/pooler_webhook.go — validation logic
• Official docs: docs/src/connection_pooling.md

Key API Fields (PgBouncerSpec)#

The spec.pgbouncer block (type PgBouncerSpec) is required. Key fields:

spec.type targets the cluster service: rw (primary), ro (replicas), or r (all instances), defaulting to rw 15. spec.instances defaults to 1 16. The spec.cluster reference is immutable after creation 17.

Automated vs. Manual Integration#

The operator distinguishes two modes via IsAutomatedIntegration():

• Automated (default): No authQuery, authQuerySecret, or serverTLSSecret set. The operator fully manages the auth user, certificates, and lookup function.
• Manual: Any of those three fields is set. The operator steps back and the user takes full responsibility for authentication setup. An admission warning is emitted in this case 18.

What automated integration provisions#

The operator automatically 19:

1. Creates the cnpg_pooler_pgbouncer PostgreSQL role
2. Creates the public.user_search() function in the postgres database (with a pinned search_path for security)
3. Issues a TLS certificate for that role
4. Configures PgBouncer to use cnpg_pooler_pgbouncer as auth_user and postgres as auth_dbname
5. Cleans up everything when no poolers reference the cluster

The default auth query is SELECT usename, passwd FROM public.user_search($1) 20, and the auth secret name falls back to <cluster-name>-pooler (suffix -pooler) 21.

TLS: Certificates#

By default, PgBouncer reuses the cluster's own certificates 22:

• Server side (PgBouncer → PostgreSQL): falls back to "" (no custom secret; managed by the cluster) via GetServerTLSSecretName(). The server CA falls back to the cluster's server CA via GetServerCASecretNameOrDefault().
• Client side (application → PgBouncer): clientTLSSecret falls back to the cluster's server TLS secret via GetClientTLSSecretNameOrDefault(). The client CA falls back to the cluster's client CA via GetClientCASecretNameOrDefault().

Supported secret formats for custom secrets: Basic Auth, TLS, or Opaque (with keys tls.crt and tls.key) 23.

Important: Supplying your own serverTLSSecret (or authQuerySecret/authQuery) disables automated integration 24. You are then solely responsible for authentication configuration.

Admission Webhook Validation#

The PoolerCustomValidator (registered at /validate-postgresql-cnpg-io-v1-pooler) fires on create and update with failurePolicy=fail 25. It runs three validation passes 26:

1. PgBouncer config validation (validatePgBouncer)#

• spec.pgbouncer is required 27.
• authQuerySecret/serverTLSSecret and authQuery must be set together — each requires the other 28.
• All keys in spec.pgbouncer.parameters must appear in AllowedPgbouncerGenericConfigurationParameters — an explicit allowlist of ~50 PgBouncer settings. Unknown parameters are rejected as Invalid 29.

2. Cluster reference validation (validateCluster)#

• spec.cluster.name must be non-empty and must not match the pooler's own name 30.

3. Monitoring TLS validation (validateMonitoring)#

• When spec.monitoring.tls.enabled=true and spec.monitoring.enablePodMonitor=true, a clientTLSSecret is required 31. Without it, the metrics endpoint would present the cluster's certificate (whose SANs cover cluster services, not the pooler), which is surfaced as a configuration error at admission time.

Admission warnings (non-blocking)#

• Manual integration mode emits a warning that the operator won't handle cluster integration 18.
• Use of the deprecated authQuerySecret field emits a deprecation warning 32.
• Use of deprecated spec.monitoring fields (e.g., enablePodMonitor, relabeling configs) emits a warning to migrate to a manually created PodMonitor 33.

Lifecycle & Status#

The Pooler progresses through four phases 34:

status.phaseReason provides a human-readable explanation. status.secrets tracks ResourceVersions of all referenced TLS and auth secrets, enabling the controller to detect secret rotations. status.error records the latest admission validation error 35.

Helm Chart Support#

The cloudnative-pg/charts cluster chart renders Pooler resources from the poolers values array 36. Each entry supports name, instances, type, poolMode, authQuerySecret, authQuery, parameters, pg_hba, and template. TLS secret fields (serverTLSSecret, clientTLSSecret, etc.) are not yet surfaced in the chart template and must be added via the raw template escape hatch or a separate Pooler manifest.