CloudNativePG — Production-Grade PostgreSQL Operator for Kubernetes

Introduction

CloudNativePG (CNPG) started inside EnterpriseDB and is now a CNCF Sandbox project. It brings an opinionated, production-ready way to run PostgreSQL on Kubernetes, covering failover, upgrades, object-storage backups and the split-brain scenarios that make DIY HA Postgres so hard.

What CloudNativePG Does

• Deploys Primary + Replica PostgreSQL clusters using streaming replication
• Handles planned and unplanned failover via a leader-election style controller
• Automates WAL archiving and base backups to S3, GCS or Azure Blob
• Performs point-in-time recovery (PITR) from backups
• Rolls upgrades of PostgreSQL minor versions with controlled switchovers

Architecture Overview

A single operator Deployment reconciles Cluster, Backup, ScheduledBackup and Pooler resources. Each Postgres instance runs in its own Pod with a sidecar-free design — the instance manager binary inside the Pod supervises PostgreSQL, ships WALs, and exposes gRPC endpoints to the operator. Replicas stream WAL directly from the primary. Failover uses PodDisruptionBudgets plus the operator election algorithm to promote a candidate with the lowest lag.

Self-Hosting & Configuration

• Install via static manifest, Helm chart or OLM bundle
• Configure backups by creating a Backup or ScheduledBackup referencing object-storage credentials
• Use PoolerSpec to spin up PgBouncer for connection pooling
• Tune postgresql.parameters and bootstrap.initdb for DBA-level control
• Observe via the built-in Prometheus exporter and Grafana dashboards

Key Features

• No Patroni, no etcd cluster, no stolon — self-contained operator
• Declarative backups with scheduled base backups + WAL archiving
• Hot standbys, read-only services and explicit primary/replica Services
• Online minor-version upgrades and major-version switchovers
• Synchronous, streaming and quorum replication options

Comparison with Similar Tools

• Zalando postgres-operator — mature, Patroni-based; CNPG avoids Patroni entirely
• Crunchy Postgres for Kubernetes — feature-rich commercial option; CNPG is fully OSS
• Stolon — older Postgres HA; less active than CNPG
• KubeDB — multi-database operator; CNPG specialises in PostgreSQL
• Helm charts + manual HA — works, but leaves failover and backups to you

FAQ

Q: Does CNPG require an external consensus store like etcd? A: No. The operator leverages the Kubernetes API as the source of truth and does not run Patroni or etcd alongside Postgres.

Q: How are backups stored? A: WALs and base backups stream to S3-compatible object storage; you can restore any cluster to any PIT within your retention window.

Q: Can I run CNPG in multi-cluster setups? A: Yes. Replica clusters can follow a primary in another Kubernetes cluster via WAL shipping for DR scenarios.

Q: Is PgBouncer included? A: Yes. The Pooler CRD provisions a PgBouncer Deployment with authentication hooked into the Cluster.

Sources

• https://github.com/cloudnative-pg/cloudnative-pg
• https://cloudnative-pg.io/documentation/