PostgreSQL on Kubernetes — Complete Setup Guide with CloudNativePG

#kubernetes #postgres #devops #cloudnative

Originally published on DevToolHub, where I keep this guide updated as CloudNativePG evolves.

Running PostgreSQL in Kubernetes used to be a bad idea. StatefulSets were tricky, persistent volumes were unreliable, and failover meant data loss. Most teams defaulted to managed cloud databases and called it done.

That calculus has changed. CloudNativePG — the CNCF-listed PostgreSQL operator — handles high availability, automated failover, Point-in-Time Recovery, connection pooling, and streaming replication out of the box. In 2026 it's the production-grade way to run PostgreSQL on Kubernetes, and the gap between "self-hosted on K8s" and "managed cloud database" has narrowed significantly.

This guide walks through a complete CloudNativePG setup — from operator install to production-ready cluster.

What the full guide covers

Why CloudNativePG over a plain StatefulSet — what the operator actually does that raw StatefulSets can't
Installing the operator — kubectl and the kubectl-cnpg plugin
Deploying a 3-instance HA cluster — 1 primary + 2 standbys, with PostgreSQL tuning parameters
Connecting your app — read-write vs read-only services, port-forwarding for debugging
Backup and WAL archiving to S3 — ScheduledBackup, retention policies, verifying archiving works
PgBouncer connection pooling — the Pooler resource, transaction vs session mode
RBAC and Network Policies — locking down who can reach the database at the Kubernetes layer
Testing failover — how to simulate a primary failure and what to expect
Point-in-Time Recovery — restoring to an exact timestamp from WAL archives
Common mistakes and best practices — storage sizing, pool mode, pg_hba.conf defaults, synchronous replication

The one thing most guides skip

WAL archiving must be configured before you put data in the database — you can't retroactively enable PITR. Configure backups before your first application write.

So which setup should you use?

CloudNativePG on K8s — right for teams with Kubernetes expertise who want full operational control, PITR, and custom PostgreSQL configuration without paying managed database prices.

Managed PostgreSQL (RDS, Cloud SQL, DigitalOcean Managed Databases) — still wins on operational simplicity. Zero operator to maintain, automatic failover handled for you.

CloudNativePG narrows the gap significantly — but the right call depends on your team's tolerance for database operations.

I keep the full step-by-step guide on DevToolHub, including all YAML manifests and kubectl commands: PostgreSQL on Kubernetes — Complete Setup Guide with CloudNativePG

I write hands-on DevOps and Kubernetes guides at devtoolhub.com. Questions about your setup? Drop a comment.