PGO, the Crunchy Data Postgres Operator: Declarative PostgreSQL Clusters on Kubernetes

What PGO Actually Manages, and for Whom

PGO is a Kubernetes operator that watches a PostgresCluster custom resource and reconciles the Deployments, StatefulSets, Services, Secrets and Jobs needed to run PostgreSQL. The README frames the goal as a declarative Postgres solution that automatically manages your PostgreSQL clusters, designed for GitOps workflows. The audience is therefore narrow and specific: platform teams that already run Kubernetes and want database lifecycle to be a manifest change rather than a ticket, a runbook, or a hand-run pg_basebackup.

The project ships as the orchestration layer inside Crunchy Postgres for Kubernetes, which the README describes as the integrated product containing PostgreSQL, PGO and a collection of PostgreSQL tools and extensions. That packaging matters more than it first appears. PGO is not a thin controller you point at any Postgres image you like; the documented installation path downloads container images from Crunchy Data's Developer Portal, and the README states plainly that using PGO outside Crunchy Postgres for Kubernetes requires modifying the installation instructions and building the necessary PostgreSQL and related containers yourself. If you want the operator without the distribution, you are on your own for image construction.

The feature list is broad: provisioning with scaling and deletion, high availability with automated failover backed by a distributed consensus solution, standby clusters within and across Kubernetes clusters, pgBackRest backups and restores including full, incremental and differential backups with delta restores, enforced TLS, pgMonitor-based monitoring, connection pooling through pgBouncer, and cluster cloning. Each of those is a subsystem with its own configuration surface, which is the real cost of adoption: you are not learning one tool, you are learning the operator plus pgBackRest plus pgBouncer plus pgMonitor plus the Crunchy Postgres image conventions.

How Reconciliation and Failover Work Under the Manifest

The mechanism is the standard controller-runtime pattern. The repository's go.mod pins sigs.k8s.io/controller-runtime v0.24.1 alongside k8s.io/api, k8s.io/apimachinery and k8s.io/client-go at v0.36.3, and the Dockerfile builds a single binary from ./cmd/postgres-operator. The operator runs as a container whose CMD is postgres-operator, built on debian:bookworm, running as USER 2, with its SQL query configuration copied to /opt/crunchy/conf and licenses to /licenses. That layout tells you the runtime is a non-root process with a read-only-ish configuration directory, not a privileged agent.

High availability is described in the README as safe, automated failover backed by a distributed consensus high availability solution, with Pod anti-affinity used for resiliency and a configurable aggressiveness. Failed primaries automatically heal. The README also notes the choice between asynchronous and synchronous replication for workloads sensitive to losing transactions, which is the decision that actually determines your recovery point objective. Synchronous replication costs you write latency and availability during a node loss; asynchronous replication means a failover can lose the most recent transactions. PGO exposes the choice, it does not make it for you.

Backups and restores are delegated to pgBackRest, which the README calls out as the open source utility behind the disaster recovery features. That delegation is why the Makefile has a get-pgmonitor target that clones CrunchyData/pgmonitor at PGMONITOR_VERSION v5.2.1 and copies postgres_exporter query files into hack/tools/queries, which the Dockerfile then bakes into the image at /opt/crunchy/conf. Monitoring is therefore not a plugin you enable at runtime; the metric queries are compiled into the operator image at build time. If you want different queries, you rebuild the image.

Installing PGO and Creating a First Cluster

The README points at the v5 Quickstart as the recommended path and then gives a shortcut. The shortcut works from the examples repository, which you fork and clone. The clone command is given with a placeholder for your GitHub username.

YOUR_GITHUB_UN="<your GitHub username>"
git clone --depth 1 "[email protected]:${YOUR_GITHUB_UN}/postgres-operator-examples.git"
cd postgres-operator-examples

From inside that directory, the README gives two kustomize commands. The first creates the namespace, the second installs the operator itself with server-side apply, which is required for the larger CRDs.

kubectl apply -k kustomize/install/namespace
kubectl apply --server-side -k kustomize/install/default

After those two commands the operator is running in its namespace and you create a cluster by applying a PostgresCluster manifest from the examples directory. The repository keeps example manifests under examples/postgrescluster/ and an optional pgAdmin example under examples/pgadmin/. The README does not spell out the manifest contents in the text reproduced here, so read the file you intend to apply before applying it; the Quickstart and Tutorial pages linked from the README are where the field-by-field explanation lives.

Two things to expect. First, the installation pulls a series of container images from Crunchy Data's Developer Portal, so an air-gapped cluster needs a mirroring step that the README does not describe. Second, the operator enforces TLS on all connections, so your first application connection will need the certificates the operator generates rather than a plaintext connection string.

Where PGO Gets in Your Way

The distribution coupling is the biggest constraint and it is stated openly. PGO is made available as the orchestration behind Crunchy Postgres for Kubernetes, and the documented install downloads images from Crunchy Data's portal. Teams that must build every image from source, or that have a policy against pulling from a vendor portal, are looking at a materially different project than the one the Quickstart installs.

The operator also assumes it can hold cluster-scoped permissions and manage CRDs. Server-side apply is required for the install, which means your cluster needs a Kubernetes version and API server configuration that supports it, and your GitOps tooling needs to handle CRD updates rather than treating them as immutable. If your platform team gates CRD changes behind a separate approval process, every PGO upgrade becomes a two-step release.

TLS enforcement is a design choice with operational consequences. The README says PGO enforces that all connections are over TLS and that you can bring your own TLS infrastructure instead of the defaults. That is good for compliance and annoying for debugging: a psql session that fails because of an expired or mismatched certificate looks like a connection error, not a certificate error, unless you know to look. The README does not document a supported way to disable TLS enforcement, which is the correct reading of the feature description but worth knowing before you plan a migration.

Finally, the project is Kubernetes-only by construction. Nothing in the repository suggests a path for Postgres on virtual machines or on a managed platform. If your database does not live in a Kubernetes cluster, PGO is the wrong tool and no amount of manifest editing changes that.

PGO Compared with Other Postgres Operators

The obvious comparison is with the Zalando postgres-operator, which is the other widely known operator in this space and appears repeatedly in what people search for alongside this project. The architectural difference is in what the operator owns. Zalando's operator is built around Patroni for leader election and its own image assembly, and it is designed to work with a lighter set of assumptions about the surrounding distribution. PGO instead couples the operator to Crunchy Postgres for Kubernetes and to pgBackRest for backup and restore, which is why the backup story is a documented subsystem rather than a hook you wire up yourself.

The second comparison is with CloudNativePG, which also appears in search queries next to this project. CloudNativePG is a CNCF project that treats the PostgreSQL instance manager as part of the operator's own design, and it has its own backup approach built on the Kubernetes API rather than on pgBackRest. The practical difference for an adopter is where the complexity lives: with PGO you learn pgBackRest configuration and the Crunchy image conventions, with CloudNativePG you learn that project's own instance manager and backup CRDs.

A third framing that shows up in search is the operator as a component of a larger data platform, for example alongside Airflow. That is a reasonable pattern: PGO gives you the cluster and the connection Secret, and the workflow scheduler connects to it like any other Postgres endpoint. PGO does not try to be a scheduler or a data catalog, and it should not be evaluated as one.

Maintenance, Upgrades and Licence Terms

The repository is not archived and the last push was on 2026-09-16, so the project is being worked on. The most recent releases listed are v6.0.2 and v5.8.8, both dated 2026-06-02, with v6.0.1 on 2026-02-26. Two maintained lines in parallel is a deliberate choice: v5 is the line the README's Quickstart links to, and v6 is the newer major line. Confirm which line your installation targets before you plan an upgrade, because the Quickstart URL in the README points at v5.

The upgrade cost inside a cluster is documented as a feature rather than a chore. The README describes upgrade management that safely applies PostgreSQL updates with minimal impact to availability, and rolling updates that roll out disruptive changes with minimal downtime. Minimal is doing real work in both sentences. A PostgreSQL minor version change still restarts the database processes, and the operator's job is to sequence that across the cluster so a primary is not the first thing to go down. Test the sequence against your storage class before you trust it in production.

The licence is Apache-2.0, which the repository states in LICENSE.md and in the SPDX header of the Dockerfile. That covers the operator source. It does not cover the container images pulled from Crunchy Data's Developer Portal, and the README explicitly directs readers to its License and Terms section for the use of those images and other third party sources. Treat the operator licence and the image terms as two separate questions, and read the terms that apply to the images your installation actually pulls.

Editorial conclusion

Adopt PGO if you already run Kubernetes, want Postgres declared in Git alongside your other workloads, and are willing to install Crunchy Postgres for Kubernetes rather than assembling your own PostgreSQL images. Do not adopt it if you cannot run an operator with cluster-scoped permissions, if you need a managed database with no control plane to operate, or if your Postgres runs outside Kubernetes. Before rolling it out, verify three things against the v5 Quickstart: which container registry your installation pulls from, whether the default TLS certificates satisfy your policy, and how your storage class behaves during the rolling update that a PostgreSQL minor version change triggers.

Frequently asked questions

Official sources

1. CrunchyData/postgres-operator on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases