Cloud Native Postgres CNPG

Ngomba Litombe

2 min read

·

May 18, 2026

--

Listen

Share

Press enter or click to view image in full size

CloudNativePG is a Kubernetes operator that covers the lifecycle of a highly available PostgreSQL database cluster with a primary/standby architecture, using native streaming replication.

CNPG key parts

• Operator: Controller running in the cnpg-system namespace that watches CNPG CRDs and reconciles PostgreSQL state.
• Cluster (CRD): The primary resource. Defines a PostgreSQL cluster (instances, storage, backups, config). A postgreSQL cluster can have multiple instances (pods).
• cnpg instance: One Pod = one PostgreSQL server. CNPG manages one primary + N replicas (streaming replication, no Patroni needed).
• Pooler (CRD): PgBouncer in front of the cluster for connection pooling.
• Backup / ScheduledBackup (CRDs): On-demand or cron-style backups to object storage (S3, GCS, Azure).
• Services auto-created: <cluster>-rw → primary (read-write) <cluster>-ro → replicas only (read-only) and <cluster>-r → any instance (read, including primary).

Operator install

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.24/releases/cnpg-1.24.0.yaml
# or install via helm
helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg cnpg/cloudnative-pg -n cnpg-system --create-namespace

# to use cmds like kubectl cnpg ..... , install plugin
curl -sSfL https://github.com/cloudnative-pg/cloudnative-pg/raw/main/hack/install-cnpg-plugin.sh | sudo sh -s -- -b /usr/local/bin

minimal cluster setup is given below. This would automatically provision secrets, services , pods etc . You can see a cnpg cluster and a logical postgres database. Note that you can use a variety of postgres images include timescaleDB.

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: pg-demo
  namespace: db
spec:
  instances: 3       # one pod would be picked as primary and the other replicas
  imageName: ghcr.io/cloudnative-pg/postgresql:16.4-3
  storage:
    size: 10Gi
    storageClass: standard
  postgresql:
    parameters:
      max_connections: "200"
      shared_buffers: "256MB"
  bootstrap:
    initdb:
      database: appdb
      owner: appuser
      secret:
        name: appuser-credentials
-----
apiVersion: v1
kind: Secret
metadata:
  name: appuser-credentials
data:
  username: admin
  password: pass

The cnpg plugin is also very useful for quick cluster operations. kubectl cnpg psql cluster-name ; would lauch a psql client for you to run your sql commands quickly without having to exec in the pod.

CNPG vs Normal postgres deployment Kubernetes

Press enter or click to view image in full size