Deploying a Highly Available PostgreSQL on Kubernetes Cluster

The example below provisions a three-node, highly available PostgreSQL cluster using the CloudNativePG operator. The primary and its synchronous replicas are distributed across availability zones, continuous WAL archiving is enabled to object storage, and connection pooling is handled inside the cluster. This is the type of production-ready blueprint MinervaDB tailors and hardens for each client.

postgres-cluster.yaml

# Highly available PostgreSQL cluster with CloudNativePG
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: minervadb-pg-prod
  namespace: databases
spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:16.3
  primaryUpdateStrategy: unsupervised

  postgresql:
    parameters:
      max_connections: "200"
      shared_buffers: "2GB"
      work_mem: "32MB"
      wal_compression: "on"

  storage:
    size: 200Gi
    storageClass: fast-ssd

  # Continuous backup and point-in-time recovery to object storage
  backup:
    barmanObjectStore:
      destinationPath: s3://minervadb-pg-backups/prod
      s3Credentials:
        accessKeyId:
          name: backup-creds
          key: ACCESS_KEY_ID
      retentionPolicy: "30d"

Applying the manifest is a single declarative command. The operator then reconciles the desired state, bootstraps the primary, streams data to replicas, and registers the cluster for continuous monitoring.

Deploy & verify

# Deploy and verify the cluster
kubectl apply -f postgres-cluster.yaml
kubectl get cluster minervadb-pg-prod -n databases
kubectl get pods -n databases -l cnpg.io/cluster=minervadb-pg-prod

# Check replication and promote-ready status
kubectl cnpg status minervadb-pg-prod -n databases

Health-check queries confirm that streaming replication is active and replicas are caught up before the cluster is opened to production traffic:

Replication health checks

-- Confirm replicas are streaming and in sync
SELECT client_addr, state, sync_state,
       replay_lag
FROM pg_stat_replication;

-- Verify the node is a primary accepting writes
SELECT CASE WHEN pg_is_in_recovery()
       THEN 'replica' ELSE 'primary' END AS role;

Understanding PostgreSQL on Kubernetes: Architecture Fundamentals

To run PostgreSQL well on Kubernetes, it helps to understand how a database — a fundamentally stateful workload — maps onto a platform originally designed for stateless, ephemeral containers. Early skepticism about databases on Kubernetes stemmed from exactly this tension. Today, that gap has been closed by StatefulSets, PersistentVolumes, the Container Storage Interface (CSI), and purpose-built operators that encode decades of database operational knowledge into software.

At the heart of any production deployment is the concept of the operator pattern. An operator is a custom controller that extends the Kubernetes API with database-specific resources and reconciliation logic. Instead of manually managing pods, services, and volumes, you declare a single high-level object — a PostgreSQL cluster — and the operator continuously works to make reality match your declared intent. If a primary pod fails, the operator promotes a healthy replica. If a node is drained, the operator reschedules pods while preserving data. This closed-loop automation is what makes Postgres on Kubernetes dependable at scale.

Persistent storage is the other cornerstone. PostgreSQL requires durable, low-latency block storage that survives pod restarts and rescheduling. Through the CSI, Kubernetes provisions PersistentVolumes backed by cloud block storage, local NVMe, or software-defined storage. Selecting the right storage class — balancing IOPS, throughput, durability, and cost — is one of the most consequential decisions in a deployment, and one where MinervaDB's experience prevents expensive missteps.

Networking ties it together. Kubernetes Services provide stable endpoints that route application traffic to the current primary for writes and across replicas for reads, even as the underlying pods change. Combined with connection pooling, this abstraction lets applications connect to a single logical endpoint while the platform transparently handles failover and scaling underneath.

Scaling PostgreSQL on Kubernetes

Scaling PostgreSQL on Kubernetes is more nuanced than scaling stateless services, and it is one of the areas where thoughtful architecture pays the greatest dividends. MinervaDB helps you choose the right scaling strategy for your access patterns rather than reaching for the most complex option first.

Read scaling is usually the first lever. By adding streaming replicas and routing read-only queries to them, you offload the primary and increase overall throughput. Operators make adding replicas nearly effortless, but application awareness matters: not every query tolerates the slight replication lag of an asynchronous replica, so we help you segment read traffic that can safely be served from replicas versus reads that must hit the primary.

Connection pooling is essential at scale. PostgreSQL allocates a backend process per connection, so thousands of application connections can exhaust server memory. Deploying PgBouncer inside the cluster multiplexes many client connections onto a small pool of database connections, dramatically improving efficiency and stability. In Kubernetes, the pooler can be scaled independently and placed close to the database for minimal latency.

When a single primary can no longer absorb write volume, horizontal sharding or distributed extensions such as Citus come into play. These approaches partition data across multiple PostgreSQL nodes, allowing writes and storage to scale horizontally. Sharding introduces real complexity around routing, cross-shard queries, and rebalancing, so we deploy it deliberately — only when the workload genuinely warrants it, and always with a clear operational runbook.

Your Roadmap to Production PostgreSQL on Kubernetes

Adopting PostgreSQL on Kubernetes is a strategic journey best taken in deliberate stages, and MinervaDB provides a clear, low-risk roadmap that turns an ambitious platform goal into dependable production reality. The path typically begins with a discovery and assessment phase in which we map your current databases, workloads, compliance obligations, and growth expectations. This groundwork ensures the target architecture is grounded in your real requirements rather than assumptions.

Next comes platform design, where we select the Kubernetes distribution, PostgreSQL operator, storage classes, and network topology that best fit your goals. We document the reference architecture, define resource sizing, and establish the security and compliance controls that will govern the environment. This phase produces a blueprint your teams can understand, review, and trust.

Implementation and migration follow. We provision the cluster using declarative, version-controlled manifests, integrate backups and monitoring from the outset, and rehearse the cutover before executing it. Data-integrity checks and a tested rollback plan keep the migration safe, and careful scheduling keeps downtime minimal or, in many cases, negligible. Throughout, we favor automation and GitOps so the platform is reproducible and auditable rather than hand-crafted and fragile.

Finally, the environment transitions into steady-state operations. Here MinervaDB provides continuous monitoring, proactive tuning, patching, capacity planning, and 24×7 incident response. We hold regular reviews to keep the platform optimized for security, availability, performance, and cost as your workloads evolve. Throughout every stage we prioritize knowledge transfer, so your engineers grow more capable and self-sufficient with each engagement. Whether you are just beginning to explore cloud-native databases or you are ready to standardize hundreds of PostgreSQL clusters across your organization, this staged approach de-risks the journey and accelerates your time to value.