---
id: v1.24
title: Release notes for CloudNativePG 1.24
---

# Release notes for CloudNativePG 1.24
<!-- SPDX-License-Identifier: CC-BY-4.0 -->

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

For a complete list of changes, please refer to the
[commits](https://github.com/cloudnative-pg/cloudnative-pg/commits/release-1.24)
on the release branch in GitHub.


## Version 1.24.4

**Release date:** May 23, 2025

:::warning
    This is the final release in the 1.24.x series.
    Users are strongly encouraged to upgrade to a newer minor version, as 1.24
    is no longer supported.
:::

### 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) <!-- no 1.22 -->

- 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)

### 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).

- 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)

- CloudNativePG Interface (CNPG-I):

  - Implemented automatic reloading of TLS certificates for plugins when they
    change. (#7029) <!-- no 1.22 -->

  - Ensured the operator properly closes the plugin connection when
    performing a backup using the plugin. (#7095, #7096) <!-- no 1.22 -->

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

- `cnpg` plugin:

  - 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.24.3

**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)
- 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.24.2

**Release Date:** December 23, 2024

### Enhancements

- Enable customization of startup, liveness, and readiness probes through the
  `.spec.probes` stanza. (#6266)
- 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:
    - 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)

## Version 1.24.1

**Release date:** Oct 16, 2024

### Enhancements:

- Remove the use of `pg_database_size` from the status probe, as it caused
  high resource utilization by scanning the entire `PGDATA` directory to
  compute database sizes. The `kubectl status` plugin will now rely on `du`
  to provide detailed size information retrieval (#5689).
- Add the ability to configure the `full_page_writes` parameter in
  PostgreSQL. This setting defaults to `on`, in line with PostgreSQL's
  recommendations (#5516).
- Plugin:
    - Add the `logs pretty` command in the `cnpg` plugin to read a log stream
      from standard input and output a human-readable format, with options to
      filter log entries (#5770)
    - Enhance the `status` command by allowing multiple `-v` options to
      increase verbosity for more detailed output (#5765).
    - Add support for specifying a custom Docker image using the `--image`
      flag in the `pgadmin4` plugin command, giving users control over the
      Docker image used for pgAdmin4 deployments (#5515).

### Fixes:

- Resolve an issue with concurrent status updates when demoting a primary to a
  designated primary, ensuring smoother transitions during cluster role changes
  (#5755).
- Ensure that replica PodDisruptionBudgets (PDB) are removed when scaling down
  to two instances, enabling easier maintenance on the node hosting the replica
  (#5487).
- Prioritize full rollout over inplace restarts (#5407).
- When using `.spec.postgresql.synchronous`, ensure that the
  `synchronous_standby_names` parameter is correctly set, even when no replicas
  are reachable (#5831).
- Fix an issue that could lead to double failover in cases of lost
  connectivity (#5788).
- Correctly set the `TMPDIR` and `PSQL_HISTORY` environment variables for pods
  and jobs, improving temporary file and history management (#5503).
- Plugin:
    - Resolve a race condition in the `logs cluster` command (#5775).
    - Display the `potential` sync status in the `status` plugin (#5533).
    - Fix the issue where pods deployed by the `pgadmin4` command didn’t have
      a writable home directory (#5800).

### Supported versions

- PostgreSQL 17 (PostgreSQL 17.0 is the default image)

## Version 1.24.0

**Release date:** Aug 22, 2024

### Important changes:

- Deprecate the `role` label in the selectors of `Service` and
  `PodDisruptionBudget` resources in favor of `cnpg.io/instanceRole` (#4897).
- Fix the default PodAntiAffinity configuration for PostgreSQL Pods,
  allowing a PostgreSQL and a Pooler Instance to coexist on the same node when
  the anti-affinity configuration is set to `required` (#5156).

:::warning
    The PodAntiAffinity change will trigger a rollout of all the instances when
    the operator is upgraded, even when online upgrades are enabled.
:::

### Features:

- **Distributed PostgreSQL Topologies**: Enhance the replica cluster feature to
  create distributed database topologies for PostgreSQL that span multiple
  Kubernetes clusters, enabling hybrid and multi-cloud deployments. This feature
  supports:
    - **Declarative Primary Control**: Easily specify which PostgreSQL cluster
      acts as the primary in a distributed setup (#4388).
    - **Seamless Switchover**: Effortlessly demote the current primary and
      promote a selected replica cluster, typically in a different region,
      without needing to rebuild the former primary. This ensures high availability
      and resilience in diverse environments (#4411).
- **Managed Services**: Introduce managed services via the `managed.services`
  stanza (#4769 and #4952), allowing you to:
    - Disable the read-only and read services via configuration.
    - Leverage the service template capability to create custom service
      resources, including load balancers, to access PostgreSQL outside
      Kubernetes (particularly useful for DBaaS purposes).
- **Enhanced API for Synchronous Replication**: Introducing an improved API for
  explicit configuration of synchronous replication, supporting both
  quorum-based and priority list strategies. This update allows full
  customization of the `synchronous_standby_names` option, providing greater
  control and flexibility (#5148).
- **WAL Disk Space Exhaustion**: Safely stop the cluster when PostgreSQL runs
  out of disk space to store WAL files, making recovery easier by increasing
  the size of the related volume (#4404).

### Enhancements:

- Add support for delayed replicas by introducing the
  `.spec.replica.minApplyDelay` option, leveraging PostgreSQL's
  `recovery_min_apply_delay` capability (#5181).
- Introduce `postInitSQLRefs` and `postInitTemplateSQLRefs` to allow users to
  define `postInit` and `postInitTemplate` instructions as one or more config
  maps or secrets (#5074).
- Add transparent support for PostgreSQL 17's `allow_alter_system` parameter,
  enabling or disabling the `ALTER SYSTEM` command through the
`.spec.postgresql.enableAlterSystem` option (#4921).
- Allow overriding the query metric name and the names of the columns using a
  `name` key/value pair, which can replace the name automatically inherited
  from the parent key (#4779).
- Enhanced control over exported metrics by making them subject to the value
  returned by a custom query, which is run within the same transaction and
  defined in the `predicate_query` field (#4503).
- Allow additional arguments to be passed to `barman-cloud-wal-archive` and
  `barman-cloud-wal-restore` (#5099).
- Introduce the `reconcilePodSpec` annotation on the `Cluster` and `Pooler`
  resources to control the restart of pods following a change in the Pod
  specification (#5069).
- The readiness probe now fails for streaming replicas that were
  never connected to the primary instance, allowing incoherent replicas
  to be discovered promptly (#5206).
- Support the new metrics introduced in PgBouncer 1.23 in the `Pooler` metrics
  collector (#5044).
- `cnpg` plugin updates:
    - Enhance the `install generate` command by adding a `--control-plane` option,
      allowing deployment of the operator on control-plane nodes by setting
      node affinity and tolerations (#5271).
    - Enhance the `destroy` command to delete also any job related to the target
      instance (#5298).
    - Enhanced the `status` command to display `demotionToken` and
      `promotionToken` when available, providing more detailed operational
      insights with distributed topologies (#5149).
    - Added support for customizing the remote database name in the `publication`
      and `subscription` subcommands. This enhancement offers greater flexibility
      for synchronizing data from an external cluster with multiple databases (#5113).

### Security:

- Add TLS communication between the operator and instance manager (#4442).
- Add optional TLS communication for the instance metrics exporter (#4927).

### Fixes:

- Enhance the mechanism for detecting Pods that have been terminated but not
  deleted during an eviction process, and extend the cleanup process during
  maintenance windows to include unschedulable Pods when the `reusePVC` flag is
  set to false (#2056).
- Disable `pg_rewind` execution for newly created replicas that employ
  VolumeSnapshot during bootstrapping to avoid introducing a new shutdown
  checkpoint entry in the WAL files. This ensures that replicas can reconnect to
  the primary without issues, which would otherwise be hindered by the additional
  checkpoint entry (#5081).
- Gracefully handle failures during the initialization of a new instance.
  Any remaining data from the failed initialization is now either removed or,
  if it's a valid PostgreSQL data directory, moved to a backup location to avoid
  possible data loss (#5112).
- Enhance the robustness of the immediate backups reconciler by implementing
  retry logic upon initial backup failure (#4982).
- Wait for the `postmaster` to shut down before starting it again (#4938).
- Ensure that the `Pooler` service template can override the default service
  (#4846).
- Exclude immutable databases from `pg_database` metric monitoring and alerting
  processes (#4980).
- Removed unnecessary permissions from the operator service account (#4911).
- Fix cluster role permissions for `ClusterImageCatalogs` (#5034).
- Ensure the operator initiates a rollout of the `Pooler` instance when
  the operator image is upgraded (#5006)
- Address race condition causing the readiness probe to incorrectly
  show "not ready" after a PostgreSQL restart, even when the
  `postmaster` was accessible (#4920).
- Prevent reconciliation of resources that aren't owned by a `Pooler` (#4967).
- Renew the certificates managed by the operator when the DNS Subject
  Alternative Names (SANs) are updated (#3269, #3319).
- Set PVC default `AccessModes` in the template only when unspecified (#4845).
- Gracefully handle unsatisfiable backup schedule (#5109).
- Synchronous replication self-healing checks now exclude terminated pods,
  focusing only on active and functional pods (#5210).
- The instance manager will now terminate all existing operator-related replication
  connections following a role change in a replica cluster (#5209).
- Allow setting `smartShutdownTimeout` to zero, enabling immediate fast
  shutdown and bypassing the smart shutdown process when required (#5347).
- `cnpg` plugin:
    - Properly handle errors during the `status` command execution.
    - Support TLS in the `status` command (#4915).

### Supported versions

- Kubernetes 1.31, 1.30, 1.29, and 1.28
- PostgreSQL 16, 15, 14, 13, and 12
    - PostgreSQL 16.4 is the default image
    - PostgreSQL 12 support ends on November 12, 2024

