CloudNativePG v1.28.0
Release Notes
Release date: Dec 9, 2025
Features
-
Quorum-Based Failover Promoted to Stable: Promoted the quorum-based failover feature, introduced experimentally in 1.27.0, to a stable API. This data-driven failover mechanism is now configured via the
spec.postgresql.synchronous.failoverQuorumfield, graduating from the previousalpha.cnpg.io/failoverQuorumannotation. (#8589) -
Declarative Foreign Data Management: Introduced comprehensive declarative management for Foreign Data Wrappers (FDW) by extending the
DatabaseCRD. This feature adds the.spec.fdwsand.spec.serversfields, allowing you to manage FDW extensions and their corresponding foreign servers directly from theDatabaseresource. This work was implemented by Ying Zhu (@EdwinaZhu) as part of the LFX Mentorship Program 2025 Term 2. (#7942, #8401)
Changes
-
Updated the default PostgreSQL version to
18.1-system-trixie. (#9178) -
Updated the default PgBouncer version to 1.25.1 for new
Poolerdeployments. (#9367)
Enhancements
-
Enabled simultaneous image and configuration changes when using
primaryUpdateMethod: restart, allowing you to update the container image (including PostgreSQL version or extensions) and PostgreSQL configuration settings in the same operation. Note that when usingprimaryUpdateMethod: switchover, image and configuration changes must still be performed separately to avoid configuration mismatches during the switchover process. (#8241) -
Improved network failure detection for replica instances by setting the default
tcp_user_timeoutto 5 seconds. This change helps replicas detect and recover from silent network drops more quickly. Previously, replicas could wait up to 127 seconds before detecting such failures; with the new timeout, they reconnect to the primary within 5 seconds. To preserve the previous behavior, setSTANDBY_TCP_USER_TIMEOUTto0in the operator configuration. (#9317) -
Adopted standard Kubernetes recommended labels (e.g.,
app.kubernetes.io/name) for all resources generated by CloudNativePG (Clusters, Backups, Poolers, etc.). Contributed by @JefeDavis. (#8087) -
Introduced
securityContextat the pod level andcontainerSecurityContextfor individual containers (includingpostgres,init, and sidecars). This provides granular control over security settings, replacing the previous cluster-widepostgresandoperatoruser settings. Contributed by @x0ddf. (#6614) -
Introduced the
alpha.cnpg.io/unrecoverable=trueannotation for replica pods. When applied, this annotation instructs the operator to permanently delete the instance by removing its Pod and PVCs, after which it will recreate the replica from the primary. (#8178) -
Introduced a new caching layer for user-defined monitoring queries to reduce load on the PostgreSQL database. (#8003)
-
Enhanced PgBouncer integration by automatically setting
auth_dbnameto thepgbouncerdatabase, simplifying auth setup. (#8671) -
Allowed providing stage-specific
pg_restoreoptions (preRestore,postRestore,dataRestore) during database import. Contributed by @hanshal101. (#7690) -
Added the PostgreSQL
majorVersionto theBackupobject's status for easier identification and management. (#8464) -
Enhanced cluster restore to wait for all init containers to complete before starting the restore process. This ensures that backup tools running in init containers finish preparing the data before the restore begins. The implementation correctly handles Kubernetes init container sidecars by ignoring those with
RestartPolicy=Always. (#9026) -
Added the
PGBOUNCER_IMAGE_NAMEoperator configuration parameter to allow overriding the default PgBouncer image. This is useful for air-gapped environments or when using internal registries. (#9232) -
cnpgplugin:-
Added a
--timeoutflag to thekubectl cnpg statuscommand for configuring the timeout for filesystem operations such as calculating cluster size. The default remains 10 seconds but can be adjusted for large clusters where operations may take longer. (#9201) -
Improved
cnpg reportto generate more shell-friendly file names. (#8984)
-
Security
-
Allowed providing fine-grained custom TLS configurations for PgBouncer. The
PoolerCRD was extended withclientTLSSecret,clientCASecret,serverTLSSecret, andserverCASecretfields under.spec.pgbouncer. These fields enable users to supply their own certificates for both client-to-pooler and pooler-to-server connections, taking precedence over the operator-generated certificates. (#8692) -
Added optional T
[truncated]