# CloudNativePG — Production-Grade PostgreSQL Operator for Kubernetes

> CloudNativePG is a Level V Kubernetes operator that manages PostgreSQL clusters with streaming replication, online backups, point-in-time recovery and rolling upgrades — without any external pgBouncer-like layer.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# CloudNativePG — PostgreSQL Operator for Kubernetes

## Quick Use
```bash
# Install the operator
kubectl apply -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.24/releases/cnpg-1.24.0.yaml

# Create a 3-node cluster
kubectl apply -f - <<EOF
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: pg
spec:
  instances: 3
  storage:
    size: 10Gi
EOF

# Check primary / replicas
kubectl cnpg status pg
```

## 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/

---
Source: https://tokrepo.com/en/workflows/cloudnativepg-production-grade-postgresql-operator-e1ff9c2c
Author: AI Open Source