Release notes for CloudNativePG 1.25

History of user-visible changes in the 1.25 minor release of CloudNativePG.

For a complete list of changes, please refer to the commits on the release branch in GitHub.

Version 1.25.4

Release date: Oct 23, 2025

Changes

• Adopted the new format of postgres-containers and postgis-containers images and image catalog artifacts, and updated the default PostgreSQL version to 18.0-system-trixie (PostgreSQL 18 is now supported). (#8578, #8760, #8558)

• Deprecated the monitoring.enablePodMonitor field in the Cluster and Pooler resources. This field will be removed in a future release. Users who rely on PodMonitor resources should create them manually instead. (#8753)

Enhancements

• Added support for overriding the PgBouncer auth_type, server_tls_sslmode, and client_tls_sslmode settings, which were previously hardcoded. Default values remain consistent with the former behavior but can now be customized when required. (#8674)

• Added a CHECKPOINT step before PostgreSQL smart and fast shutdowns to reduce shutdown duration and replica promotion time, especially on systems with a high checkpoint_timeout. (#8867)

• Added a warning in the instance manager for deprecated or unsupported OS versions, based on the official postgres-containers project. (#8601)

• Improved certificate parsing error reporting. Failures now log specific errors instead of a generic message, aiding troubleshooting. This is particularly relevant after the CVE-2025-58187 fix in Go 1.25.2 and 1.24.8, which may trigger parsing failures for invalid DNS SANs. (#8801)

• Added a check to ensure the destination WAL archive path is empty when bootstrapping a cluster using the pg_basebackup method, consistent with other bootstrap methods. (#8895)

• Added validation to prevent backups from running on hibernated clusters. Backups attempted on such clusters now fail with reason ClusterIsHibernated, following the standard prerequisite check pattern. (#8870)

• Added support for pprof profiling. Instances can now enable the pprof tool by adding the alpha.cnpg.io/enableInstancePprof annotation to the Cluster resource for advanced debugging. (#7876)

• cnpg plugin:

• Updated the Flexible I/O Tester (FIO) image to wallnerryan/fiotools-aio:v2, as provided by Ryan Wallner. (#8847)

• Enhanced the cnpg status backup command to provide more detailed status information when using a barman-cloud-based backup plugin. (#8780, #8690)

Fixes

• Fixed backup restoration failures when using custom WAL segment sizes with parallel WAL recovery. The operator no longer manages the end-of-WAL file marker during restoration, preventing errors when backups span multiple WAL segments. (#8873)

• Fixed a bug in major upgrades where a volume snapshot from a previous minor version could be incorrectly used to optimize replica creation. (#8475)

• Fixed initdb to wait for the application user secret before bootstrapping a new cluster, preventing potential race conditions. (#8663)

• Fixed the connection retry logic in the cnpgi plugin. The reconciliation loop now detects connection pool changes correctly and uses exponential backoff to reduce "closed pool" errors. (#8554)

• Fixed volume snapshot usage during replica scaling to work with backup plugins. Previously, this optimization was only available with the in-tree backup implementation, but now clusters using backup plugins can also leverage volume snapshots when creating new replicas. (#8506)

• Fixed the Pooler templating to correctly inherit settings for the bootstrap controller init container. (#8394)

• Fixed webhook errors to use the correct API group (postgresql.cnpg.io) in Pooler and backup webhooks, ensuring consistent API error reporting. (#8485)

• Fixed a potential nil pointer dereference in the hibernation reconciler when handling errors. Contributed by @PascalBourdier. (#8756)

• Fixed an issue in the environment cache where callers could inadvertently modify shared data. The LoadEnv function now returns a copy of cached environment slices to prevent mutations from affecting the cache. (#8880)

Version 1.25.3

Release date: Jul 25, 2025

In memory of DJ Walker-Morgan.

Changes

• Removed 386 and ARM (v5/v6/v7) architectures from the cnpg plugin build matrix, reducing the number of published binaries (#7648).

Enhancements

• Improved validation of shared_buffers by correctly considering HugePages settings, ensuring accurate memory configuration checks (#7864).

• Set oom_score_adj for PostgreSQL worker processes to improve prioritization during out-of-memory situations (#7891).

• Added fqdn-uri and fqdn-jdbc-uri fields in user secrets to simplify application connection string management and align with DNS-based connection best practices (#7852).

• Added the systemID field and related condition in the Cluster status to track the PostgreSQL system identifier. (#7717).

Fixes

• Added a mutex in the connection pooler to protect concurrent access to the connections map, improving stability in high-concurrency environments (#7804).

• Fixed replica cluster instance ordering by correctly detecting the designated primary, improving replica cluster stability and switchover operations (#8108).

• Added support for reconciling VolumeAttributesClass for PVCs, enhancing storage compatibility and lifecycle management (#7885).

• Made the internal webserver routines non-blocking to improve responsiveness under load (#8071).

• Fixed an issue where the ensureReplicationClientLeafCertificate error did not display the correct secretName in the not found message (#8086).

• Prevented invalid ALTER SUBSCRIPTION statements by updating only PostgreSQL‑supported parameters; unsupported options like copy_data are ignored to avoid reconciliation failures (7844).

• Fixed an issue where the bootstrap-controller in the connection pooler did not apply resources settings correctly (#7922).

• Ensured online backups fail cleanly if the targetPod becomes unhealthy during backup, preventing partial or misleading backups (#7944).

• Ensured the Backup resource status is set properly after a failure, improving observability and scripting reliability (#7898).

Version 1.25.2

Release date: May 23, 2025

Important Changes

• CloudNativePG is now officially a CNCF project: CloudNativePG has been accepted into the Cloud Native Computing Foundation (CNCF), marking a significant milestone in its evolution. As part of this transition, the project is now governed under CloudNativePG, a Series of LF Projects, LLC, ensuring long-term sustainability and community-driven innovation. (#7203)

Enhancements

• Added the KUBERNETES_CLUSTER_DOMAIN configuration option to the operator, allowing users to specify the domain suffix for fully qualified domain names (FQDNs) generated within the Kubernetes cluster. If not set, it defaults to cluster.local. (#6989)

• Implemented the cnpg.io/validation annotation, enabling users to disable the validation webhook on CloudNativePG-managed resources. Use with caution, as this allows unrestricted changes. (#7196)

• Added support for collecting pg_stat_wal metrics in PostgreSQL 18. (#7005)

• Added support for LZ4, XZ, and Zstandard compression methods when archiving WAL files via Barman Cloud (deprecated). (#7151)

• CloudNativePG Interface (CNPG-I):

• A plugin can now trigger instance rollouts by implementing the EVALUATE verb, ensuring that plugin-induced changes are properly reconciled. (#7126)

• Introduced support for WAL recovery via CNPG-I plugins during snapshot restore. (#7284)

Security

• Set imagePullPolicy to Always for the operator deployment to ensure that images are always pulled from the registry, reducing the risk of using outdated or potentially unsafe local images. (#7250)

Fixes

• Fixed native replication slot synchronization and logical replication failover for PostgreSQL 17 by appending the dbname parameter to primary_conninfo in replica configurations (#7298).

• Fixed a regression in WAL restore operations that prevented fallback to the in-tree barmanObjectStore configuration defined in the externalCluster source when a plugin failed to locate a WAL file (#7507).

• Improved backup efficiency by introducing a fail-fast mechanism in WAL archiving, allowing quicker detection of unexpected primary demotion and avoiding unnecessary retries (#7483).

• Fixed an off-by-one error in parallel WAL archiving that could cause one extra worker process to be spawned beyond the requested number (#7389).

• Resolved a race condition that caused the operator to perform two switchovers when updating the PostgreSQL configuration. (#6991)

• Corrected the PodMonitor configuration by adjusting the matchLabels scope for the targeted pooler and cluster pods. Previously, the matchLabels were too broad, inadvertently inheriting labels from the cluster and leading to data collection from unintended targets. (#7063)

• Added a webhook warning for clusters with a missing unit (e.g., MB, GB) in the shared_buffers configuration. This will become an error in future releases. Users should update their configurations to include explicit units (e.g., 512MB instead of 512). (#7160)

• Treated timeout errors during volume snapshot creation as retryable to prevent unnecessary backup failures. (#7010)

• Moved the defaulting logic for .spec.postgresql.synchronous.dataDurability from the CRD to the webhook to avoid UI issues with OLM. (#7600)

• CloudNativePG Interface (CNPG-I):

• Implemented automatic reloading of TLS certificates for plugins when they change. (#7029)

• Ensured the operator properly closes the plugin connection when performing a backup using the plugin. (#7095, #7096)

• Improved performance and resilience of CNPG-I by removing timeouts for local plugin operations, avoiding failures during longer backup or WAL archiving executions (#7496).

• cnpg plugin:

• Increased the buffer size in the logs pretty command to better handle larger log output (#7281).

• Ensured the plugin-name parameter is required for plugin-based backups and disallowed for non-plugin backup methods (#7506).

• Ensured that the primary Pod is recreated during an imperative restart when primaryUpdateMethod is set to restart, aligning its definition with the replicas. (#7122)

Changes

• Updated the default PostgreSQL version to 17.5 for new cluster definitions. (#7556)

• Updated the default PgBouncer version to 1.24.1 for new Pooler deployments (#7399).

Version 1.25.1

Release Date: February 28, 2025

Enhancements

• Introduced a startup probe for the operator to enhance reliability and prevent premature liveness probe failures during initialization. (#7008)
• Added support for using the -r service with the Pooler. (#6868)
• Introduced an optional --ttl flag for the pgbench plugin, enabling automatic deletion of completed jobs after a user-defined duration. (#6701)
• Marked known error messages from the Azure CSI Driver for volume snapshots as retryable, improving resilience. (#6906)
• Updated the default PostgreSQL version to 17.4 for new cluster definitions. (#6960)

Security

• The operator image build process has been enhanced to strengthen security and transparency. Images are now signed with cosign, and OCI attestations are generated, incorporating the Software Bill of Materials (SBOM) and provenance data. Additionally, OCI annotations have been added to improve traceability and ensure the integrity of the images.

Bug Fixes

• Fixed inconsistent behavior in default probe knob values when .spec.probes is defined, ensuring users can override all settings, including failureThreshold. If unspecified in the startup probe, failureThreshold is now correctly derived from .spec.startupDelay / periodSeconds (default: 10, now overridable). The same logic applies to liveness probes via .spec.livenessProbeTimeout. (#6656)
• Managed service ports now take precedence over default operator-defined ports. (#6474)
• Fixed an issue where WAL metrics were unavailable after an instance restart until a configuration change was applied. (#6816)
• Fixed an issue in monolithic database import where role import was skipped if no roles were specified. (#6646)
• Added support for new metrics introduced in PgBouncer 1.24. (#6630)
• Resolved an issue where Database, Publication, and Subscription CRDs became stuck in cluster resource has been deleted, skipping reconciliation after cluster rehydration. This patch forces status.observedGeneration to zero, ensuring proper reconciliation. (#6607)
• Improved handling of replication-sensitive parameter reductions by ensuring timely reconciliation after primary server restarts. (#6440)
• Introduced a new isWALArchiver flag in the CNPG-I plugin configuration, allowing users to designate a plugin as a WAL archiver. This enables seamless migration from in-tree Barman Cloud support to the plugin while maintaining WAL archive consistency. (#6593)
• Ensured override.conf is consistently included in postgresql.conf during replica cluster bootstrapping, preventing replication failures due to missing configuration settings. (#6808)
• Ensured override.conf is correctly initialized before invoking pg_rewind to prevent failures during primary role changes. (#6670)
• Enhanced webhook responses to return both warnings and errors when applicable, improving diagnostic accuracy. (#6579)
• Ensured the operator version is correctly reconciled. (#6496)
• Improved PostgreSQL version detection by using a more precise check of the data directory. (#6659)
• Volume Snapshot Backups:
  • Fixed an issue where unused backup connections were not properly cleaned up. (#6882)
  • Ensured the instance manager closes stale PostgreSQL connections left by failed volume snapshot backups. (#6879)
  • Prevented the operator from starting a new volume snapshot backup while another is already in progress. (#6890)
• cnpg plugin:
  • Restored functionality of the promote plugin command. (#6476)
  • Enhanced kubectl cnpg report --logs <cluster> to collect logs from all containers, including sidecars. (#6636)
  • Ensured pgbench jobs can run when a Cluster uses an ImageCatalog. (#6868)

Technical Enhancements

• Added support for Kubernetes client-gen, enabling automated generation of Go clients for all CloudNativePG CRDs. (#6695)

Version 1.25.0

Release Date: December 23, 2024

Features

• Declarative Database Management: Introduce the Database Custom Resource Definition (CRD), enabling users to create and manage PostgreSQL databases declaratively within a cluster. (#5325)

• Logical Replication Management: Add Publication and Subscription CRDs for declarative management of PostgreSQL logical replication. These simplify replication setup and facilitate online migrations to CloudNativePG. (#5329)

• Experimental Support for CNPG-I: Introducing CNPG-I (CloudNativePG Interface), a standardized framework designed to extend CloudNativePG functionality through third-party plugins and foster the growth of the CNPG ecosystem. The Barman Cloud Plugin serves as a live example, illustrating how plugins can be developed to enhance backup and recovery workflows. Although CNPG-I support is currently experimental, it offers a powerful approach to extending CloudNativePG without modifying the operator’s core code—akin to PostgreSQL extensions. We welcome community feedback and contributions to shape this exciting new capability.

Enhancements

• Add the dataDurability option to the .spec.postgresql.synchronous stanza, allowing users to choose between required (default) or preferred durability in synchronous replication. (#5878)
• Enable customization of startup, liveness, and readiness probes through the .spec.probes stanza. (#6266)
• Support additional pg_dump and pg_restore options to enhance database import flexibility. (#6214)
• Add support for maxConcurrentReconciles in the CloudNativePG controller and set the default to 10, improving the operator's ability to efficiently manage larger deployments out of the box. (#5678)
• Add the cnpg.io/userType label to secrets generated for predefined users, specifically superuser and app. (#4392)
• Improved validation for the spec.schedule field in ScheduledBackups, raising warnings for potential misconfigurations. (#5396)
• cnpg plugin:
  • Enhance the backup command to support plugins. (#6045)
  • Honor the User-Agent header in HTTP requests with the API server. (#6153)

Bug Fixes

• Ensure the former primary flushes its WAL file queue to the archive before re-synchronizing as a replica, reducing recovery times and enhancing data consistency during failovers. (#6141)
• Clean the WAL volume along with the PGDATA volume during bootstrap. (#6265)
• Update the operator to set the cluster phase to Unrecoverable when all previously generated PersistentVolumeClaims are missing. (#6170)
• Fix the parsing of the synchronous_standby_names GUC when .spec.postgresql.synchronous.method is set to first. (#5955)
• Resolved a potential race condition when patching certain conditions in CRD statuses, improving reliability in concurrent updates. (#6328)
• Correct role changes to apply at the transaction level instead of the database context. (#6064)
• Remove the primary_slot_name definition from the override.conf file on the primary to ensure it is always empty. (#6219)
• Configure libpq environment variables, including PGHOST, in PgBouncer pods to enable seamless access to the pgbouncer virtual database using psql from within the container. (#6247)
• Remove unnecessary updates to the Cluster status when verifying changes in the image catalog. (#6277)
• Prevent panic during recovery from an external server without proper backup configuration. (#6300)
• Resolved a key collision issue in structured logs, where the name field was inconsistently used to log two distinct values. (#6324)
• Ensure proper quoting of the inRoles field in SQL statements to prevent syntax errors in generated SQL during role management. (#6346)
• cnpg plugin:
  • Ensure the kubectl context is properly passed in the psql command. (#6257)
  • Avoid displaying physical backups block when empty with status command. (#5998)

Supported Versions

• Kubernetes: 1.32, 1.31, 1.30, and 1.29
• PostgreSQL: 17, 16, 15, 14, and 13
  • Default image: PostgreSQL 17.2
  • Officially dropped support for PostgreSQL 12
  • PostgreSQL 13 support ends on November 12, 2025