Skip to content
CommonLayer
Documentation menu
On this page

ADR-0015: Highly available PostgreSQL through CloudNativePG

Status: Accepted (plan decision D15). Chart implemented (projects/postgresql/charts/postgresql-ha). Install, failover, rolling update and helm test ran once, green, on a GitHub runner (2026-11-10); the next run, after the test moved into a chart hook, failed (amended 2026-11-10).

Context

Many Helm charts call a StatefulSet with several replicas "high availability". It is not: without leader election, fencing and replica promotion, losing the primary means an outage and manual intervention. Writing that machinery into a chart is out of reach for a community project.

Decision

  • Offer two charts. postgresql is a single instance and its README says plainly that it is not highly available. postgresql-ha renders a CloudNativePG Cluster (and optionally a Pooler and ScheduledBackup) that runs the CommonLayer PostgreSQL image.
  • Patroni was evaluated (projects/postgresql/docs/HIGH-AVAILABILITY.md); an established operator was chosen because failover, fencing, switchover and backups are its job.
  • CommonLayer maintains the image and the chart; the operator is upstream's. CommonLayer does not ship or patch the operator, which is a cluster-level controller with its own security boundary.

Consequences

  • The image works as a CloudNativePG operand without a dedicated variant: binaries on PATH, postgresUID/postgresGID: 10001, a passwd entry for UID 10001, and the HA chart renders repository:tag@digest because the operator parses the major version from the tag (WP-22).
  • Backups use the Barman Cloud Plugin or volume snapshots; no Barman tools in the image.
  • What is not verified: operator installation, bootstrap, failover, switchover, rolling updates, helm test, backups, the Pooler, PodMonitor, NetworkPolicy enforcement, synchronous replication and arm64. scripts/test-ha-kind.sh exists for CI but has never run because kind does not start in the build sandbox. Until it has run, treat the HA chart as unproven.

Amendment, 2026-11-10

  • The kind test ran on a GitHub-hosted runner on 2026-11-10 (projects run 42882522865, commit a562cb9) and passed: CloudNativePG 1.30.1 installed, three instances ready, the primary killed and a standby promoted (t-ha-postgresql-ha-3, about 3 s), data kept, the old primary rejoined as a standby, rolling update and helm test passed. That is one run on linux/amd64 with kind.
  • The test then moved from scripts/test-ha-kind.sh into the chart hooks projects/postgresql/tests/kind/postgresql-ha.* (WP-70f). Its first run in that form (projects run 42901650680, commit d907c7c) failed in the wait hook, which looked for a Cluster named t-postgresql-ha-postgresql-ha while the release had created t-postgresql-ha. Until the hook form passes, the HA test is not part of a green run.
  • Still not verified: backups (Barman Cloud Plugin, volume snapshots), the Pooler, PodMonitor, NetworkPolicy enforcement on a policy-enforcing CNI, synchronous replication, switchover by an operator, arm64, and anything on a real cluster.