percona/percona-postgresql-operator v3.0.0

on GitHub

Release highlights

Crunchy CRD renaming and seamless resource migration

With this release, all Crunchy CRDs are renamed and moved under a new API group upstream.pgv2.percona.com. All references to Crunchy CRDs in dependent objects, such as Custom Resources, Deployments, Secrets, ConfigMaps, Jobs, and so on, are updated accordingly.

When you update from the earlier Operator versions to 3.0.0 and newer, new API group CRDs are created alongside the legacy CRDs to keep existing workflows uninterrupted. Then the Operator automatically migrates all resources that depend on the legacy CRDs to the new API group. No manual intervention is required.

Important: As part of the API group migration, the common name in the pgBackRest client certificate is updated. The Operator automatically updates both the pgBackRest configuration and the related certificate Secret. However, you may experience brief disruptions to pgBackRest operations while Kubernetes propagates these changes to the containers. This process typically completes within 1–2 minutes.

The migration event is recorded in cluster conditions and logs, so you have full visibility into what happened and when.

This change delivers these benefits:

• Safe coexistence of Percona Operator for PostgreSQL and Crunchy PGO
• Cleaner API boundaries and predictable Operator behavior
• Smooth migration from Crunchy Operator to Percona Operator using native PostgreSQL techniques and without re-architecting your deployments

For how to migrate to Percona Operator from Crunchy PGO, see our documentaton.

Improved namespace scoping for Operator OLM installations from Community catalogues

When you install the Operator from a Community catalogue through OpenShift Lifecycle Manager (OLM), it now honors the namespace scope as defined by its OperatorGroup settings:

• All namespaces — The Operator watches all namespaces, as intended for this mode. In earlier releases, it watched only its own installation namespace, which left PostgreSQL custom resources in other namespaces unmanaged.
• Single namespace — The Operator watches only the namespaces listed for the OperatorGroup (olm.targetNamespaces), so a scoped install stays scoped.

With this change, you get the same namespace coverage your subscription mode promises, so clusters behave the way OpenShift administrators expect.

After you upgrade, the Operator may begin reconciling Percona PostgreSQL custom resources that already exist in namespaces it previously ignored. That is most common when several Operators run in one OpenShift cluster, all in all-namespaces mode, and each installation now actually honors that mode.

Before you upgrade, confirm how the Operator is installed by inspecting the OperatorGroup: a single entry under spec.targetNamespaces means single-namespace mode; an empty value means all-namespaces mode.

To limit which namespaces an Operator reconciles, set spec.targetNamespaces explicitly:

spec:
  targetNamespaces:
    - "<namespace-1>"
    - "<namespace-2>"

If you run more than one Operator in the same cluster, switch each one to single-namespace mode so their reconciliation work does not overlap in ways you did not intend.

Official Docker image for major version upgrades

Starting with this release, the Operator performs major upgrades using the official Percona Docker image: percona/percona-distribution-postgresql-upgrade:<available-upgrade-versions>.

Refer to our major upgrade documentation for detailed instructions, including the updated image path.

Deprecation, Change, Rename and Removal

• The support of version 2.7.0 is dropped from CRDs.

Changelog

Improvements

• K8SPG-1007 - Renamed upstream Custom Resource Definitions (CRDs) to simplify migration from other PostgreSQL operators. This change allows users to install the Percona Operator for PostgreSQL alongside existing installations without resource conflicts or API group overlapping.

• K8SPG-1019 - Improved the codebase with performance optimizations, tooling, language ergonomics, and security by applying Go 1.26 using go fix.

• K8SPG-1022 - Updated the major upgrade documentation to include critical instructions for the pgaudit extension. Users are now guided to drop and reinstall the extension during the upgrade process to ensure it functions correctly on the new version.

Fixed bugs

• K8SPG-737 - Fixed an issue where disk usage statistics were not accessible by PMM node_exporter in PostgreSQL pods. The update ensures the data directory is correctly exposed to the monitoring sidecar, enabling full visibility into storage metrics through PMM.

• K8SPG-999 - Fixed a bug where only the first extension was removed when attempting to drop multiple custom extensions. The updated logic ensures all targeted extensions are correctly deleted, maintaining consistency between the Custom Resource specification and the database state. (Thank you Matan Haver for contributing to this issue)

• K8SPG-1017 - Resolved a critical issue where upgrading to version 2.9.0 caused TLS configurations to unexpectedly switch from the internal PKI to cert-manager. This fix prevents unwanted certificate re-issuance and service disruption for clusters that rely on the Operator's internal certificate management.

Documentation updates

• Created Migration from Crunchy Postgres Operator to Percona Operator for PostgreSQL tutorials
• Improved the major upgrade description for users of pgAudit extension.
• Database cluster upgrade documentation now uses PostgreSQL 18 as the default example in upgrade commands. If you are upgrading a cluster running PostgreSQL 17 or below, refer to the certified images list to determine the correct version and image tags.

Supported software

This Operator version is developed, tested and based on:

• PostgreSQL 14.23-1, 15.18-1, 16.14-1, 17.10-1, 18.4-1 as the database. Other versions may also work but have not been tested.
• pgBackRest 2.58.0-2 for backup and recovery
• pgBouncer 1.25.2-1 for connection pooling
• Patroni version 4.1.3 for high-availability
• PostGIS version 3.5.6
• PMM Client version 2.44.1-1 and 3.7.1

Supported platforms

Percona Operators are designed for compatibility with all CNCF-certified Kubernetes distributions.

Our release process includes targeted testing and validation on major cloud provider platforms and OpenShift, as detailed below:

• Google Kubernetes Engine (GKE) 1.33 - 1.35
• Amazon Elastic Container Service for Kubernetes (EKS) 1.33 - 1.35
• OpenShift 4.18 - 4.21
• Azure Kubernetes Service (AKS) 1.33 - 1.35
• Minikube 1.38.1 with Kubernetes v1.35.1

This list only includes the platforms that the Percona Operators are specifically tested on as part of the release process. Other Kubernetes flavors and versions depend on the backward compatibility offered by Kubernetes itself.