PostgreSQL High Availability Architecture

This page describes how KubeBlocks deploys a PostgreSQL high-availability (HA) cluster on Kubernetes — covering the resource hierarchy, pod internals, traffic routing, and automatic failover.

Resource Hierarchy

KubeBlocks models a PostgreSQL cluster as a hierarchy of Kubernetes custom resources:

Cluster  →  Component  →  InstanceSet  →  Pod × N

Containers Inside Each Pod

Every PostgreSQL pod runs four containers:

An init container (pg-init-container) runs postgres-pre-setup.sh before the main containers start to initialize the data directory and configuration files.

Each pod mounts its own PVC (data-{ordinal}, default 20 Gi) at /home/postgres/pgdata, providing independent persistent storage.

High Availability via Patroni

KubeBlocks uses Patroni for PostgreSQL HA. By default the Kubernetes API is used as the DCS (Distributed Configuration Store); etcd can optionally be used instead by providing a serviceRef to an etcd cluster.

On startup, every pod joins the Patroni cluster under the same scope. Patroni holds a leader election by atomically acquiring the leader annotation on the {scope} ConfigMap; the winner becomes primary and the others stream WAL as replicas.

Traffic Routing

KubeBlocks creates two services for each PostgreSQL cluster:

The key mechanism is roleSelector: primary on the ClusterIP service. KubeBlocks probes each pod's role via dbctl every second and updates the pod label kubeblocks.io/role. The service's Endpoints therefore always point at the current primary — no VIP or external load balancer required.

• Read/write traffic: connect to {cluster}-postgresql-postgresql:5432 or :6432 (pgbouncer)
• Direct pod access (e.g., read replicas, Patroni heartbeats): use the headless service DNS pod-N.{cluster}-postgresql-headless.{namespace}.svc.cluster.local

Automatic Failover

When the primary pod fails, the following sequence restores service automatically:

1. Primary pod crashes (process death, node failure, network partition)
2. Patroni detects heartbeat timeout — the leader lease expires (TTL ≈ 30 s)
3. Replica acquires the lease — the first healthy replica to atomically update the leader annotation on the {scope} ConfigMap wins and promotes itself to primary
4. KubeBlocks detects the role change — the dbctl role probe returns primary for the new winner
5. Pod label updated — kubeblocks.io/role=primary is applied to the new primary pod
6. Service Endpoints switch — the ClusterIP service automatically routes traffic to the new primary

Total failover time is typically within 30–60 seconds, bounded by Patroni's TTL and the role probe interval.

For a planned switchover (e.g., maintenance), KubeBlocks calls the Patroni switchover API via switchover.sh, which performs a graceful demotion of the current primary and promotion of a chosen replica with no data loss.

System Accounts

KubeBlocks automatically creates and manages the following PostgreSQL system accounts. Passwords are auto-generated and stored in Secrets named {cluster}-{component}-account-{name}.