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.
Reconcile loop Cluster YAML API server watch event OperatorDeployment create / patch Pods / PVCsServices / Secrets Instance manager status report, drift repeats the loop
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.

ServicePoints to
app-db-rwPrimary only
app-db-roReplicas only
app-db-rAny instance
Writers always use -rw.
App Pod app-db-rw app-db-ro writes reads PrimaryPVC 1 ReplicaPVC 2 ReplicaPVC 3 WALstreaming S3 / GCSAzure WAL archive + base backup go to object storage

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.
KindWhat it does
ClusterThe Postgres cluster
BackupOne backup request
ScheduledBackupCron style backups
PoolerPgBouncer pooling
DatabaseDeclarative DB
DatabaseRoleDeclarative role
Publication / SubscriptionLogical replication
ImageCatalog / ClusterImageCatalogImage per Postgres major (namespace, cluster-wide)
FailoverQuorumSync failover quorum (with failoverQuorum)
ObjectStoreThe 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 / switchoverDelay tune the timing.
The Leasespec.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

TopicDIY STSCNPG
FailoverManual or PatroniBuilt in
ReplicasYou script theminstances: N
Backups / PITRYour cron jobsBackup CRDs
PodsOrdinal orderLowest free serial (1.30) : a recreated instance keeps its name
ConfigEdit, restartRolling update
Passwords / TLSHand madeGenerated
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 over until 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"
  1. Install operator into cnpg-system.
  2. Apply a Cluster with instances: 3.
  3. Operator makes primary Pod and PVC, then clones replicas.
  4. It adds -rw, -ro, -r Services and the app-db-app Secret.
  5. App connects to app-db-rw.apps.svc:5432.
  6. Failover is automatic. WAL ships only once a WAL archiver plugin is set up (next sheet).
Clusterapp-db the operatorbuilds these Pods app-db-1 / 2 / 3+ one PVC each Servicesapp-db-rw / -ro / -r Secretapp-db-app (user + password)
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 with Expected empty archive.
  • Or back up with volume snapshots.
Cluster app-db + plugin sidecar archives bucket WAL + base backups plugins: ObjectStore barmancloud.cnpg.io points at restore new Cluster its own serverName
# 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 sts shows nothing : look at pods, pvc, clusters.

2.Useful Commands

CommandDescription
helm repo add cnpg https://cloudnative-pg.io/chartsAdd the chart repo (the old github.io address redirects here)
helm upgrade --install cnpg -n cnpg-system --create-namespace cnpg/cloudnative-pgInstall the operator
kubectl get cluster -n appsList CNPG clusters
kubectl cnpg status app-dbHealth, primary, lag
kubectl cnpg promote app-db app-db-2Manual switchover
kubectl cnpg psql app-dbpsql on the primary
kubectl cnpg backup app-db -m plugin --plugin-name barman-cloud.cloudnative-pg.ioOn-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.