PostgreSQL

Production-ready PostgreSQL deployment with support for standalone and streaming replication architectures, structured access controls, TLS, External Secrets Operator, optional replication slots, and production hardening controls.

Key Features

• Standalone and replication — Single instance or primary with streaming replicas
• Automatic initialization — Init scripts, extensions, and custom configuration
• S3 backup — Scheduled backups to S3-compatible storage via CronJob
• Metrics — Prometheus exporter with ServiceMonitor
• Security — Non-root containers, TLS support with private-key permission normalization, structured pg_hba.conf CIDRs, NetworkPolicy controls, and ServiceAccount token control
• Replication slots — Optional physical slots with WAL retention limits for safer replica catch-up behavior
• External Secrets Operator — Optional external-secrets.io/v1 resources for auth, TLS, and backup credentials
• Persistent storage — Configurable PVCs with storage class selection

Architecture

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install my-pg helmforge/postgresql

OCI registry:

helm install my-pg oci://ghcr.io/helmforgedev/helm/postgresql

Deployment Examples

# values.yaml
architecture: standalone

auth:
  postgresPassword: 'my-secret-password'
  database: myapp
  username: myuser
  password: 'user-password'

standalone:
  persistence:
    enabled: true
    size: 20Gi

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

# values.yaml
architecture: replication

auth:
  postgresPassword: 'my-secret-password'
  database: myapp
  username: myuser
  password: 'user-password'
  replicationPassword: 'repl-password'

replication:
  primary:
    persistence:
      enabled: true
      size: 20Gi
  readReplicas:
    replicaCount: 2
    persistence:
      enabled: true
      size: 20Gi

# values.yaml
architecture: standalone

auth:
  postgresPassword: 'my-secret-password'
  database: myapp

standalone:
  persistence:
    enabled: true
    size: 20Gi

backup:
  enabled: true
  schedule: '0 3 * * *'
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: my-pg-backups
    accessKey: '<set-me>'
    secretKey: '<set-me>'

# values.yaml
architecture: standalone

auth:
  postgresPassword: 'my-secret-password'
  database: myapp

standalone:
  persistence:
    enabled: true
    size: 20Gi

tls:
  enabled: true
  existingSecret: postgresql-tls
  sslMode: require
  volumePermissions:
    enabled: true

# values.yaml - production baseline with replication, TLS, slots, backup, and policies
architecture: replication

auth:
  existingSecret: postgresql-auth
  database: app
  username: app

config:
  localAuthMethod: scram-sha-256
  allowedClientCIDRs:
    - 10.42.0.0/16
  allowedReplicationCIDRs:
    - 10.42.0.0/16

replication:
  primary:
    persistence:
      size: 100Gi
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
      limits:
        cpu: '2'
        memory: 2Gi
  readReplicas:
    replicaCount: 2
    persistence:
      size: 100Gi
  wal:
    keepSize: 2GB
    maxReplicationSlots: 10
    maxSlotWalKeepSize: 8GB
    walSenderTimeout: 60s
  slots:
    enabled: true

tls:
  enabled: true
  existingSecret: postgresql-tls
  sslMode: require
  volumePermissions:
    enabled: true

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

networkPolicy:
  enabled: true
  egress:
    enabled: true
    allowDNS: true
    allowSameNamespacePostgreSQL: true
    allowHTTPS: true

serviceAccount:
  create: true
  automountServiceAccountToken: false

backup:
  enabled: true
  s3:
    endpoint: https://s3.example.com
    bucket: postgresql-backups
    existingSecret: postgresql-backup

# values.yaml - render ExternalSecret resources for existing ESO clusters
auth:
  existingSecret: postgresql-auth

tls:
  enabled: true
  existingSecret: postgresql-tls

backup:
  enabled: true
  s3:
    existingSecret: postgresql-backup

externalSecrets:
  enabled: true
  apiVersion: external-secrets.io/v1
  secretStoreRef:
    name: platform-secrets
    kind: ClusterSecretStore
  auth:
    enabled: true
    targetName: postgresql-auth
    postgresPasswordRemoteRef:
      key: prod/postgresql
      property: postgres-password
    userPasswordRemoteRef:
      key: prod/postgresql
      property: user-password
    replicationPasswordRemoteRef:
      key: prod/postgresql
      property: replication-password
  tls:
    enabled: true
    targetName: postgresql-tls
    certRemoteRef:
      key: prod/postgresql-tls
      property: tls.crt
    keyRemoteRef:
      key: prod/postgresql-tls
      property: tls.key
    caRemoteRef:
      key: prod/postgresql-tls
      property: ca.crt
  backup:
    enabled: true
    targetName: postgresql-backup
    accessKeyRemoteRef:
      key: prod/postgresql-backup
      property: access-key
    secretKeyRemoteRef:
      key: prod/postgresql-backup
      property: secret-key

Production Path

The default install remains intentionally suitable for local development and disposable test clusters. A production deployment should explicitly set existing Secrets or External Secrets, storage, resources, config.allowedClientCIDRs, config.allowedReplicationCIDRs, TLS, metrics, backup, and NetworkPolicy behavior.

Use the structured CIDR lists first. config.pgHbaEntries and raw config.pgHba remain escape hatches for advanced cases, but production baselines should not depend on a full raw pg_hba.conf override.

Replication slots are disabled by default for compatibility. If replication.slots.enabled=true, also set WAL limits such as replication.wal.maxSlotWalKeepSize so a stalled replica cannot retain unbounded WAL.

Operational Notes

• The chart keeps internal health checks, metrics, and built-in backup on PostgreSQL’s standard postgres database.
• If a reused PVC contains a valid data directory but is missing the default postgres database, the primary pod repairs that database during startup before normal readiness checks rely on it.
• auth.database remains the application bootstrap database. It is created only on first initialization of a fresh data directory.
• Set initdb.runDefaultScript=false when custom or externally managed init scripts should run without the chart-generated application and replication user bootstrap script.
• docker-entrypoint-initdb.d scripts only run when the data directory is empty. Existing PVCs keep their current roles and databases during upgrades.

Dual-stack Networking

PostgreSQL Services accept Kubernetes dual-stack configuration. By default, both service.ipFamilyPolicy and service.ipFamilies are unset and the chart inherits whatever the cluster advertises (matching prior behavior). Setting them propagates to every chart-managed Service: client, primary, replicas, metrics, and the headless StatefulSet services.

service:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv4
    - IPv6

PreferDualStack is the safer choice for clusters that may be single- or dual-stack: omit ipFamilies and the cluster auto-populates whatever it supports. Set ipFamilies explicitly only when the cluster is configured for both families — the Kubernetes API rejects an explicit family the cluster does not advertise. RequireDualStack enforces both.

Configuration Reference

This reference covers the complete values.yaml surface for the PostgreSQL chart.

Core

Image

Authentication

PostgreSQL Configuration

TLS

Initialization

Standalone

Replication - Primary

Replication - Read Replicas

Replication - WAL, PDB, and Scheduling

Service

Metrics

Backup

NetworkPolicy

Pod Disruption Budget

Service Account

Probes

Scheduling and Security

Extra

External Secrets Operator

Upgrade Notes

• When switching from standalone to replication, set auth.replicationPassword before upgrading
• PVC resize requires the storage class to support volume expansion (allowVolumeExpansion: true)
• Metrics sidecar changes may cause a pod restart during upgrade

Common Issues

More Information

• Blog guide: Deploy Production-Ready PostgreSQL on Kubernetes
• PostgreSQL Official Website
• PostgreSQL Official Documentation
• PostgreSQL Docker Official Image
• HelmForge PostgreSQL Chart Source