PostgreSQL Highly Available

Overview

PostgreSQL Highly Available deploys a production-ready PostgreSQL cluster using Patroni for automatic leader election and failover, with etcd providing distributed consensus. An optional HAProxy workload routes all write traffic to the current primary replica, providing a stable connection endpoint regardless of which replica holds the leader role.

For production use, maintain at least 3 PostgreSQL replicas and 3 etcd replicas. etcd requires an odd number of replicas (3, 5, 7) for quorum.

What Gets Created

Stateful Patroni PostgreSQL Workload — A Patroni-managed PostgreSQL cluster with configurable replica count and resources. Each replica has its own volume. Leadership is gracefully handed off before any replica is shut down, ensuring write availability is maintained during deployments and restarts.
etcd Workload — A dedicated etcd cluster providing distributed consensus for Patroni leader election.
HAProxy Leader-Routing Workload (optional, enabled by default) — Routes write traffic to the current primary replica, providing a stable connection endpoint during failover.
PgBouncer Workload (optional) — A connection pooler deployed in front of HAProxy, multiplexing application connections into a smaller pool of real database connections.
Volume Set — Persistent storage for PostgreSQL data, with optional autoscaling.
Secrets — A dictionary secret with database credentials; opaque secrets for the Patroni startup script, HAProxy startup script, and WAL-G backup script (created as needed).
Identity & Policy — An identity bound to the workload with reveal access to all required secrets, and cloud storage access when backup is enabled.

This template does not create a GVC. You must deploy it into an existing GVC.

Installation

This template has no external prerequisites unless backup is enabled. To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

The default values.yaml for this template:

replicas: 3

resources:
  minCpu: 500m
  minMemory: 1Gi
  maxCpu: 1
  maxMemory: 2Gi

image: controlplanecorporation/patroni-postgres:0.7

postgres:
  username: username
  password: password
  database: test

multiZone: false

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false
    maxCapacity: 100 # Maximum capacity in GiB
    minFreePercentage: 10 # Trigger scaling when free space drops below this percentage
    scalingFactor: 1.2 # Multiply current capacity by this factor when scaling up

internal_access:
  type: same-gvc # options: same-gvc, same-org, workload-list
  workloads: # Note: can only be used if type is same-gvc or workload-list
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

etcd:
  replicas: 3
  resources:
    cpu: 500m
    memory: 512Mi
  multiZone: false
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)
  internal_access:
    type: same-gvc # options: same-gvc, same-org, workload-list
    workloads:
      #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

pgbouncer:
  enabled: false
  image: edoburu/pgbouncer:v1.25.1-p0
  poolMode: transaction  # options: session, transaction, statement
  defaultPoolSize: 25    # number of real Postgres connections PgBouncer maintains per pod
  maxClientConn: 1000    # maximum number of client connections PgBouncer accepts per pod
  maxDbConnections: 100  # hard cap on total Postgres connections regardless of how many PgBouncer pods are running
  minReplicas: 2
  maxReplicas: 4

  resources:
    cpu: 200m
    memory: 128Mi

proxy: # HAProxy endpoint to write to leader replica. Automatically enabled when pgbouncer is enabled.
  enabled: true
  image: haproxy:2.9
  resources:
    cpu: 100m
    memory: 128Mi
  minReplicas: 2
  maxReplicas: 2

backup:
  enabled: false
  mode: logical  # logical or wal-g
  resources:
    cpu: 100m
    memory: 128Mi

  logical:
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0 # tag 17.1.0 = Postgres 17, 18.1.0 = Postgres 18
    schedule: "0 2 * * *" # cron schedule, default is daily at 2am UTC

  walg:
    intervalSeconds: 21600 # interval in seconds between backups, default is every 6 hours

  # storage settings are applied to whichever mode is enabled
  provider: aws # Options: aws, gcp, or minio

  aws:
    bucket: pg-ha-backup-bucket
    region: us-east-1
    cloudAccountName: my-s3-cloud-account
    policyName: pg-ha-backup-policy
    prefix: postgres/backups

  gcp:
    bucket: pg-ha-backup-bucket
    cloudAccountName: my-gcs-cloud-account
    prefix: postgres/backups

  minio: # Backup to a self-hosted MinIO workload (or any S3-compatible endpoint)
    endpoint: http://my-minio-workload:9000 # e.g. http://WORKLOAD_NAME:9000 for an internal MinIO template deployment
    bucket: pg-ha-backup-bucket
    accessKey: my-minio-username # matches the MinIO template's admin.username
    secretKey: my-minio-password # matches the MinIO template's admin.password
    prefix: postgres/backups

Credentials

postgres.username — PostgreSQL superuser username. Change before deploying to production.
postgres.password — PostgreSQL superuser password. Change before deploying to production.
postgres.database — Name of the database created on first startup.

These values are only applied on first startup when the data directory is empty. Updating them after the initial deployment will have no effect on the running database. To change credentials or the database name on an existing instance, use PostgreSQL’s native commands (e.g. ALTER USER, ALTER DATABASE).

PostgreSQL Cluster

replicas — Number of PostgreSQL replicas. Minimum 3 recommended for production.
resources.minCpu / resources.minMemory — Minimum CPU and memory guaranteed per replica.
resources.maxCpu / resources.maxMemory — Maximum CPU and memory per replica.
multiZone — Spread replicas across availability zones within the location.

Storage

volumeset.capacity — Initial volume size in GiB (minimum 10). Each replica gets its own volume.
volumeset.autoscaling.enabled — Automatically expand the volume as it fills. When enabled:
- maxCapacity — Maximum volume size in GiB.
- minFreePercentage — Trigger a scale-up when free space drops below this percentage.
- scalingFactor — Multiply the current capacity by this factor when scaling up.

etcd Cluster

etcd.replicas — Number of etcd replicas. Must be an odd number (3, 5, 7) for quorum.
etcd.resources.cpu / etcd.resources.memory — CPU and memory per etcd replica.
etcd.multiZone — Spread etcd replicas across availability zones.
etcd.volumeset.capacity — Initial volume size for etcd data in GiB.
etcd.internal_access.type — Controls which workloads can reach the etcd cluster.

HAProxy (Strongly Recommended)

In a Patroni cluster, only the leader replica accepts writes — other replicas are read-only. HAProxy automatically routes write traffic to the current leader, providing a stable connection endpoint even during failover. HAProxy exposes two HTTP endpoints on the proxy workload for observability:

Endpoint	Description
`:8404/healthz`	Returns healthy when at least one primary backend is reachable, unhealthy otherwise
`:8405/stats`	Live stats page showing connection counts and the health status of each replica

proxy.enabled — Deploy the HAProxy leader-routing workload (default: true).
proxy.resources.cpu / proxy.resources.memory — CPU and memory per HAProxy replica.
proxy.minReplicas / proxy.maxReplicas — Replica count for the proxy workload.

HAProxy must be enabled (proxy.enabled: true) for logical backups to function correctly. WAL-G backups do not require the proxy.

Internal Access

internal_access.type — Controls which workloads can connect to PostgreSQL on port 5432:

Type	Description
`same-gvc`	Allow access from all workloads in the same GVC
`same-org`	Allow access from all workloads in the same organization
`workload-list`	Allow access only from specific workloads listed in `workloads`

PgBouncer Connection Pooling

PgBouncer is an optional connection pooler that sits in front of HAProxy, multiplexing application connections into a smaller pool of real database connections. HAProxy handles leader routing and failover transparently — PgBouncer is unaware of which PostgreSQL replica is the primary. Enabling PgBouncer automatically enables HAProxy, as it is required for leader-aware routing in the HA cluster. When enabled, PgBouncer becomes the primary connection endpoint:

RELEASE_NAME-pgbouncer.GVC_NAME.cpln.local:5432

pgbouncer.poolMode — Controls how connections are reused:

Mode	Description
`transaction`	Connection held only for the duration of a transaction, then returned to the pool. Best for most web and API workloads. Not compatible with session-level features (`SET` variables, temporary tables, advisory locks).
`session`	Connection held for the entire client session. Compatible with all PostgreSQL features but provides less reuse. Increase `defaultPoolSize` to match your expected concurrent client count.
`statement`	Connection returned after every statement. Transactions are not supported. Rarely used.

pgbouncer.defaultPoolSize — Number of real PostgreSQL connections PgBouncer maintains per pod (default: 25).
pgbouncer.maxClientConn — Maximum number of client connections PgBouncer accepts per pod (default: 1000).
pgbouncer.maxDbConnections — Hard cap on total PostgreSQL connections across all PgBouncer pods. Prevents connection blowout when PgBouncer scales out — set this to a value the PostgreSQL primary can safely handle (default: 100).
pgbouncer.minReplicas / pgbouncer.maxReplicas — PgBouncer autoscales on RPS between these bounds. Increase maxReplicas for high-throughput workloads.
pgbouncer.resources.cpu / pgbouncer.resources.memory — Resources allocated to each PgBouncer pod.

Application Retry Logic

Your application should implement retry logic on database connections. Several normal cluster events surface transient errors to the client:

Patroni failover — During a leader election, the old primary steps down and a new one is promoted. HAProxy detects the change and re-routes writes, but connections in flight during the transition may receive a connection reset or brief refusal.
Rolling restarts and deployments — Each replica is restarted in turn. Leadership is handed off gracefully before the leader shuts down, but applications may see a momentary connection disruption while the new leader is established and HAProxy updates its routing.
Scale down — Removing replicas triggers a shutdown sequence. If the departing replica held the leader role, a new election occurs and writes are unavailable until the new leader is ready.

These events are expected and short-lived. Implementing exponential backoff with retry on connection errors ensures your application recovers automatically without surfacing errors to end users.

Connecting to PostgreSQL

Connect to PostgreSQL through the HAProxy workload, which always routes to the current leader:

RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local:5432

Backup

Two backup modes are available. Set backup.enabled: true, choose a mode, and configure the storage provider.

Mode	Description
`logical`	Scheduled SQL dumps via `pg_dump`. Portable and suitable for smaller databases. Requires HAProxy to be enabled.
`wal-g`	Continuous WAL archiving with point-in-time recovery. Suitable for larger databases requiring minimal data loss. Runs as a sidecar container alongside PostgreSQL.

backup.mode — logical or wal-g.
backup.provider — aws, gcp, or minio.
backup.resources.cpu / backup.resources.memory — Resources allocated to the backup container.

Logical backup settings:

backup.logical.schedule — Cron expression for backup frequency (default: daily at 2am UTC).

WAL-G backup settings:

backup.walg.intervalSeconds — Interval between base backups in seconds (default: 21600, every 6 hours).

Backup Prerequisites

AWS S3

Before enabling backup with provider: aws, complete the following in your AWS account:

Create an S3 bucket. Set backup.aws.bucket to the bucket name and backup.aws.region to its region.
If you do not have a Cloud Account set up, refer to the docs to Create a Cloud Account. Set backup.aws.cloudAccountName to its name.
Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

Set backup.aws.policyName to the name of the policy created in step 3.
Set backup.aws.prefix to the folder path where backups will be stored.

GCS

Before enabling backup with provider: gcp, complete the following in your GCP account:

Create a GCS bucket. Set backup.gcp.bucket to the bucket name.
If you do not have a Cloud Account set up, refer to the docs to Create a Cloud Account. Set backup.gcp.cloudAccountName to its name.
Add the Storage Admin role to the GCP service account associated with the Cloud Account.
Set backup.gcp.prefix to the folder path where backups will be stored.

MinIO

Before enabling backup with provider: minio, ensure your MinIO instance is accessible:

Create a bucket in MinIO. Set backup.minio.bucket to its name.
Set backup.minio.endpoint to the MinIO S3 API address including the port. For the minio marketplace template deployed in the same GVC, use http://WORKLOAD_NAME:9000.
Set backup.minio.accessKey and backup.minio.secretKey to the MinIO root credentials — these match the admin.username and admin.password values from the MinIO template installation.
Set backup.minio.prefix to the folder path where backups will be stored.

MinIO backup requires no Control Plane Cloud Account — credentials are passed directly. Both logical and wal-g modes are supported; WAL-G uses its native S3-compatible storage support (AWS_ENDPOINT + path-style addressing).

Restoring a Backup

Logical

Run the following from a client with access to the backup bucket. Connect through the proxy workload so the restore targets the current leader. AWS S3:

export PGPASSWORD="PASSWORD"

aws s3 cp "s3://BUCKET_NAME/PREFIX/BACKUP_FILE.sql.gz" - \
  | gunzip \
  | psql \
      --host=RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD

GCS:

export PGPASSWORD="PASSWORD"

gsutil cp "gs://BUCKET_NAME/PREFIX/BACKUP_FILE.sql.gz" - \
  | gunzip \
  | psql \
      --host=RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD

MinIO:

export PGPASSWORD="PASSWORD"
export AWS_ACCESS_KEY_ID="MINIO_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="MINIO_SECRET_KEY"
aws configure set default.s3.addressing_style path

aws s3 cp "s3://BUCKET_NAME/PREFIX/BACKUP_FILE.sql.gz" - --endpoint-url "http://MINIO_ENDPOINT:9000" \
  | gunzip \
  | psql \
      --host=RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

WAL-G

WAL-G point-in-time restore requires an empty data directory. Follow these steps:

Run wal-g backup-list to identify the desired backup.
Stop the PostgreSQL workload.
Create a new Volume Set for the restored data.
Run a one-off restore workload with the new Volume Set mounted at /var/lib/postgresql/data and run:

wal-g backup-fetch /var/lib/postgresql/data/pgdata <backup_name>

Re-point the PostgreSQL workload to the restored Volume Set and restart.
After the restore, change backup.walg.prefix before re-enabling backups to avoid system identifier conflicts.

External References

Patroni Documentation

Patroni automatic failover documentation

PostgreSQL Documentation

Official PostgreSQL documentation

etcd Documentation

Official etcd documentation

PgBouncer Documentation

PgBouncer configuration reference

Backup Image Source

Source code for the PostgreSQL backup container image

PostgreSQL HA Template

View the source files, default values, and chart definition

Template Catalog

Templates

PostgreSQL Highly Available

Overview

What Gets Created

Installation

UI

CLI

Terraform

Pulumi

Configuration

Credentials

PostgreSQL Cluster

Storage

etcd Cluster

HAProxy (Strongly Recommended)

Internal Access

PgBouncer Connection Pooling

Application Retry Logic

Connecting to PostgreSQL

Backup

Backup Prerequisites

AWS S3

GCS

MinIO

Restoring a Backup

Logical

WAL-G

External References

Patroni Documentation

PostgreSQL Documentation

etcd Documentation

PgBouncer Documentation

Backup Image Source

PostgreSQL HA Template

​Overview

​What Gets Created

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Credentials

​PostgreSQL Cluster

​Storage

​etcd Cluster

​HAProxy (Strongly Recommended)

​Internal Access

​PgBouncer Connection Pooling

​Application Retry Logic

​Connecting to PostgreSQL

​Backup

​Backup Prerequisites

​AWS S3

​GCS

​MinIO

​Restoring a Backup

​Logical

​WAL-G

​External References

Patroni Documentation

PostgreSQL Documentation

etcd Documentation

PgBouncer Documentation

Backup Image Source

PostgreSQL HA Template

Overview

What Gets Created

Installation

Configuration

Credentials

PostgreSQL Cluster

Storage

etcd Cluster

HAProxy (Strongly Recommended)

Internal Access

PgBouncer Connection Pooling

Application Retry Logic

Connecting to PostgreSQL

Backup

Backup Prerequisites

AWS S3

GCS

MinIO

Restoring a Backup

Logical

WAL-G

External References