Data
CloudNativePG Operator
1.What is CNPG ?
An operator that runs highly available PostgreSQL on Kubernetes. You write one Cluster YAML and it builds the Pods, volumes, services, failover and backups.
- A plain Postgres Deployment has no replication, no failover, no backups.
- StatefulSets give stable names and disks, but no Postgres knowledge.
- Operator = the DBA runbook as a reconcile loop.
- Talks to the Kubernetes API directly. No Patroni, no StatefulSet.
Notes
CNCF Incubating (TOC vote 2026-11-02; Sandbox since Jan 2025). Latest stable checked : v1.30.1. Core CRD :
postgresql.cnpg.io/v1 kind Cluster.2.Cluster Layout
One primary plus N hot standbys. Each Pod has its own PVC, no shared disk. Replication is native Postgres WAL streaming.
| Service | Points to |
|---|---|
| app-db-rw | Primary only |
| app-db-ro | Replicas only |
| app-db-r | Any instance |
Writers always use -rw.
3.Parts and CRDs
- OperatorDeployment in cnpg-system. Helm names it cnpg-cloudnative-pg, the plain manifest cnpg-controller-manager. Watches the CRDs.
- Instance managerPID 1 in every Postgres Pod. Probes, WAL archiving, promotion.
- PoolerManaged PgBouncer (rw or ro).
- Barman Cloud pluginShips WAL and backups to object storage. Separate install : cert-manager first, then into the operator's namespace.
- kubectl cnpgCLI plugin for status, promote, psql.
| Kind | What it does |
|---|---|
| Cluster | The Postgres cluster |
| Backup | One backup request |
| ScheduledBackup | Cron style backups |
| Pooler | PgBouncer pooling |
| Database | Declarative DB |
| DatabaseRole | Declarative role |
| Publication / Subscription | Logical replication |
| ImageCatalog / ClusterImageCatalog | Image per Postgres major (namespace, cluster-wide) |
| FailoverQuorum | Sync failover quorum (with failoverQuorum) |
| ObjectStore | The plugin's bucket config (barmancloud.cnpg.io) |
In short : CNPG turns one
Cluster YAML into a primary plus streaming replicas, each with its own PVC, behind -rw / -ro / -r Services.1.Failover
Automatic inside one Kubernetes cluster. Across clusters it is manual : promote the replica cluster yourself.
failoverDelay/switchoverDelaytune the timing.
The Lease
spec.primaryLease (15/10/2/1 s) : a Lease named after the Cluster, held by the primary's Pod. A promotion gate, not a fence.
Failover Flow
Primary fails
Operator detectstarget pending, old primary unhealthy (out of -rw)
Pick replicamost advanced, once every WAL receiver is down
Promotetakes the Lease, then -rw follows
Old primaryrejoins as replica
2.CNPG vs DIY StatefulSet
| Topic | DIY STS | CNPG |
|---|---|---|
| Failover | Manual or Patroni | Built in |
| Replicas | You script them | instances: N |
| Backups / PITR | Your cron jobs | Backup CRDs |
| Pods | Ordinal order | Lowest free serial (1.30) : a recreated instance keeps its name |
| Config | Edit, restart | Rolling update |
| Passwords / TLS | Hand made | Generated |
Failover timings
- A graceful delete of the primary waits up to 180 s for open sessions (the smart shutdown) before the failover starts.
- After a node loss the phase stays
Failing overuntil the old Pod is evicted, even though a replica is already promoted.
3.Try It
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: app-db
namespace: apps
spec:
instances: 3
storage:
size: 10Gi
postgresql:
parameters:
max_connections: "200"
- Install operator into cnpg-system.
- Apply a Cluster with instances: 3.
- Operator makes primary Pod and PVC, then clones replicas.
- It adds -rw, -ro, -r Services and the app-db-app Secret.
- App connects to app-db-rw.apps.svc:5432.
- Failover is automatic. WAL ships only once a WAL archiver plugin is set up (next sheet).
In short : Declare a Cluster and CNPG runs Postgres for you : Pods, PVCs, -rw/-ro/-r Services and failover, with no StatefulSet. Backups need a plugin.
1.Backups Need a Plugin
The in-tree barmanObjectStore is deprecated since v1.26 and goes in v1.32.0 (#11671). Backups and WAL archiving now come from a plugin, most often the Barman Cloud plugin.
- Install cert-manager first. The plugin runs in the operator's namespace.
- An
ObjectStore(barmancloud.cnpg.io) names the bucket and its keys. - The Cluster lists it under
plugins:. Nothing is archived until then. - Recovery always makes a new Cluster. If it archives too, give it its own
serverName: the source's fails withExpected empty archive. - Or back up with volume snapshots.
# in the Cluster's spec
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: my-store
Without this entry, applying a Cluster archives nothing, and the Cluster still reads healthy.
Watch out
- Delete a Cluster and its PVCs go, data included. The safety net is the bucket and the snapshots : Backup objects hold no data, and Poolers keep running, inactive.
- instances: 1 means no HA, and its primary PDB makes its node undrainable. Use 3 across nodes : the default anti-affinity is only preferred.
- The default image is the deprecated system flavour. Pin a dated minimal tag plus its digest : a bare digest is refused.
- Never write via a Pod IP or -r.
kubectl get stsshows nothing : look at pods, pvc, clusters.
2.Useful Commands
| Command | Description |
|---|---|
| helm repo add cnpg https://cloudnative-pg.io/charts | Add the chart repo (the old github.io address redirects here) |
| helm upgrade --install cnpg -n cnpg-system --create-namespace cnpg/cloudnative-pg | Install the operator |
| kubectl get cluster -n apps | List CNPG clusters |
| kubectl cnpg status app-db | Health, primary, lag |
| kubectl cnpg promote app-db app-db-2 | Manual switchover |
| kubectl cnpg psql app-db | psql on the primary |
| kubectl cnpg backup app-db -m plugin --plugin-name barman-cloud.cloudnative-pg.io | On-demand backup through the plugin. Without -m plugin it asks for barmanObjectStore and fails : the cluster has no backup section |
In short : Backups and WAL archiving need a plugin, the Barman Cloud plugin with cert-manager, and a restore is always a new Cluster with its own serverName.