Release notes for CloudNativePG 1.28 ==================================== .. _release-notes-for-cloudnativepg-1.28-1: Release notes for CloudNativePG 1.28 ==================================== History of user-visible changes in the 1.28 minor release of CloudNativePG. For a complete list of changes, please refer to the `commits `_ on the release branch in GitHub. .. raw:: html Version 1.28.1 -------------- **Release date:** Feb 5, 2026 Enhancements ^^^^^^^^^^^^ - Added support for Azure’s ``DefaultAzureCredential`` authentication mechanism for backup and recovery operations. This can be enabled by setting ``azureCredentials.useDefaultAzureCredentials: true`` in the backup configuration, simplifying authentication in Azure environments without requiring explicit storage account keys or SAS tokens. ( `#9468 `_ ) Fixes ^^^^^ - Fixed validation of PostgreSQL extension names containing underscores (e.g., ``pg_partman`` , ``pg_ivm`` ). Extension names with underscores are automatically sanitized to use hyphens for Kubernetes volume names while preserving the original name in mount paths. Webhook validation prevents naming conflicts after sanitization. Contributed by @shusaan. ( `#9386 `_ ) - Fixed a critical issue where the ``TimelineID`` in the cluster status was not reset to 1 after a major version upgrade. Because ``pg_upgrade`` initializes a new timeline, keeping the old ID (e.g., timeline 2) caused replicas to attempt to restore incompatible history files from object storage, leading to fatal “requested timeline is not a child of this server’s history” errors. ( `#9830 `_ ) - Fixed an issue where stale TLS status fields in the ``Pooler`` were not cleared after being removed from the specification. This was particularly critical when upgrading to v1.28.0, where the ``ServerTLS`` field was repurposed, causing PgBouncer to use incorrect certificates and resulting in “unsupported certificate” errors that blocked all application connectivity. The operator now explicitly clears ``ServerCA`` , ``ClientCA`` , ``ClientTLS`` , and ``ServerTLS`` status fields when they are no longer configured. ( `#9397 `_ ) - Fixed a bug where replicas could enter a crash-loop by attempting to download timeline history files from future timelines. This occurred when stale files remained in the WAL archive from a previous cluster life, and replicas would incorrectly try to fetch them during recovery. ( `#9650 `_ ) - Fixed a race condition in ``replica_cluster`` setups during designated primary transitions, preventing transient “no primary” states in the replica cluster. ( `#9601 `_ ) - The backup controller now uses the unique instance session ID to detect instance manager restarts. This prevents the operator from incorrectly assuming a backup is still progressing if the underlying container has crashed and restarted, which previously led to orphaned backup objects. ( `#9370 `_ ) - Fixed a validation gap in Azure object store configurations where the ``storageAccount`` was not required when using explicit credentials (such as a storage key or SAS token). The operator now enforces that a storage account name is provided in these cases and that ``connectionString`` is mutually exclusive with other authentication parameters. ( `#9604 `_ ) - Optimized the deletion path so the operator begins cleaning up resources immediately when a cluster is marked for deletion. This significantly reduces the time a cluster remains in ``Terminating`` status while waiting for internal reconciliation loops. ( `#9555 `_ ) - Fixed an issue where replication slots were not properly dropped from replicas when the feature was disabled or the cluster was reconfigured. This ensures that unused slots do not cause WAL build-up on the primary. ( `#9381 `_ ) - Fixed an issue where ``imagePullSecrets`` were not added to the ``ServiceAccount`` created for the ``Pooler`` . Previously, these secrets were applied to the Deployment but not the SA, which caused image pull failures in restricted environments using certain security policies. ( `#9427 `_ ) - Added a check to verify ownership before the operator deletes a ``PodMonitor`` . This prevents the operator from accidentally deleting manually managed monitoring resources that happen to share a name with expected CNPG resources. Contributed by @juliamertz. ( `#9340 `_ ) - Fixed a bug where ``pg_stat_archiver`` metrics would continue to report stale data on standby instances after a switchover. The exporter now skips these metrics on standbys, as PostgreSQL only provides valid archiver stats on the primary. ( `#9411 `_ ) - Clarified the interpretation of timestamp formats for recovery ``targetTime`` . Timestamps provided without an explicit timezone are now consistently interpreted as UTC. Contributed by @pchovelon. ( `#8937 `_ ) - Fixed backup status updates to prevent “resource has been modified” errors during concurrent updates. ( `#9551 `_ ) - Fixed event reporting to use the correct pod name when a backup pod is not found. ( `#9552 `_ ) - Improved performance of scheduled backup operations for clusters with a very high number of historical backups. ( `#9489 `_ ) - Fixed error handling when removing finalizers on ``Database`` objects. ( `#9431 `_ ) - ``cnpg`` plugin: - Updated the ``status`` command to display “Disabled” when the ``skipWalArchiving`` annotation is present on a cluster. This replaces confusing “starting up” or “unknown” states when WAL archiving is intentionally bypassed. ( `#9709 `_ ) - Fixed the ``logs --follow`` command to continue polling for new pods instead of exiting prematurely when all current log streams complete. ( `#9599 `_ ) Version 1.28.0 -------------- **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.failoverQuorum`` field, graduating from the previous ``alpha.cnpg.io/failoverQuorum`` annotation. ( `#8589 `_ ) - **Declarative Foreign Data Management**: Introduced comprehensive declarative management for Foreign Data Wrappers (FDW) by extending the ``Database`` CRD. This feature adds the ``.spec.fdws`` and ``.spec.servers`` fields, allowing you to manage FDW extensions and their corresponding foreign servers directly from the ``Database`` resource. 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 ``Pooler`` deployments. ( `#9367 `_ ) .. _enhancements-1: 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 using ``primaryUpdateMethod: 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_timeout`` to 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, set ``STANDBY_TCP_USER_TIMEOUT`` to ``0`` in 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 ``securityContext`` at the pod level and ``containerSecurityContext`` for individual containers (including ``postgres`` , ``init`` , and sidecars). This provides granular control over security settings, replacing the previous cluster-wide ``postgres`` and ``operator`` user settings. Contributed by @x0ddf. ( `#6614 `_ ) - Introduced the ``alpha.cnpg.io/unrecoverable=true`` annotation 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_dbname`` to the ``pgbouncer`` database, simplifying auth setup. ( `#8671 `_ ) - Allowed providing stage-specific ``pg_restore`` options (``preRestore`` , ``postRestore`` , ``dataRestore`` ) during database import. Contributed by @hanshal101. ( `#7690 `_ ) - Added the PostgreSQL ``majorVersion`` to the ``Backup`` object’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_NAME`` operator configuration parameter to allow overriding the default PgBouncer image. This is useful for air-gapped environments or when using internal registries. ( `#9232 `_ ) - ``cnpg`` plugin: - Added a ``--timeout`` flag to the ``kubectl cnpg status`` command 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 report`` to generate more shell-friendly file names. ( `#8984 `_ ) Security ^^^^^^^^ - Allowed providing fine-grained custom TLS configurations for PgBouncer. The ``Pooler`` CRD was extended with ``clientTLSSecret`` , ``clientCASecret`` , ``serverTLSSecret`` , and ``serverCASecret`` fields 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 TLS support for the operator’s metrics server (port 8080). This feature is opt-in and enabled by setting the ``METRICS_CERT_DIR`` environment variable, which instructs the operator to look for ``tls.crt`` and ``tls.key`` files in the specified directory. When unset, the server continues to use HTTP for backward compatibility. ( `#8997 `_ ) - Enabled ``cnpg report operator`` to work with minimal permissions by making only the operator deployment required. All other resources (pods, secrets, config maps, events, webhooks, and OLM data) are now optional and collected on a best-efforts basis. The command gracefully handles permission errors for those resources by logging clear warnings and continuing report generation with available data, rather than failing completely. This enables least-privileged access, where users may have limited, namespace-scoped permissions. ( `#8982 `_ ) .. _fixes-1: Fixes ^^^^^ - Improved resilience of all probe types (liveness, readiness, and startup) to transient Kubernetes API server connectivity issues. Probes now use a caching mechanism that falls back to cached cluster definitions during brief network interruptions, preventing unnecessary pod restarts and probe failures. ( `#9148 `_ ) - Fixed the ``CheckEmptyWalArchive`` safeguard to run correctly when restoring from a volume snapshot using CNPG-I backup/WAL plugins (e.g., ``plugin-barman-cloud`` ). Previously, this check was skipped for plugin-based implementations. ( `#9306 `_ ) - Improved error reporting when ImageCatalog retrieval fails. The operator now emits a Warning event and logs errors for all failure types, not just ``NotFound`` errors, improving visibility into configuration issues. ( `#9266 `_ ) - Fixed TLS certificate verification issues when connecting to CNPG-I plugins by adding the ``cnpg.io/pluginServerName`` annotation. This allows customizing the DNS name used for certificate verification in environments where the plugin’s certificate uses a different DNS name than the Service name. ( `#9222 `_ ) - Fixed an issue where the instance manager controller could fail to restart after an error, reporting a “controller already exists” message. The controller now uses ``SkipNameValidation`` for subsequent initialization attempts. Contributed by @mateusoliveira43. ( `#9123 `_ ) - Fixed incorrect WAL restore path handling in plugins when the destination path is absolute, preventing path duplication issues. Contributed by @Endevir. ( `#9093 `_ ) - Fixed the ``CREATE PUBLICATION`` SQL generation for multi-table publications to be backward-compatible with PostgreSQL 13+. The previously generated syntax was only valid for PostgreSQL 15+ and caused syntax errors on older versions. ( `#8888 `_ ) - Fixed backup failures in complex pod definitions by reliably selecting the ``postgres`` container by name instead of by index. Contributed by @Joda89. ( `#8964 `_ ) - ``cnpg`` plugin: - Fixed bugs in ``cnpg report`` log collection, especially when fetching previous logs. The collector now correctly fetches previous and current logs in separate requests and gracefully handles missing previous logs (e.g., on containers with no restart history), ensuring current logs are always collected. ( `#8992 `_ ) Supported versions ^^^^^^^^^^^^^^^^^^ - Kubernetes 1.34, 1.33, and 1.32 - PostgreSQL 18, 17, 16, 15, and 14 - PostgreSQL 18.1 is the default image