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

Security Scan

Security posture is strong. Remaining findings are documented product exceptions for opt-in NetworkPolicy and PostgreSQL’s writable runtime filesystem.

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.us-east-2.amazonaws.com
    bucket: my-pg-backups
    region: us-east-2
    credentialsFromPodIdentity: true

backup:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/replace-with-your-backup-role

# 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:
    endpoint: https://s3.example.com
    bucket: postgresql-backups
    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

The backup workload identity mode never renders static S3 credentials. EKS Pod Identity requires an association for the dedicated backup ServiceAccount. IRSA uses the role annotation shown in the backup example. Keep backup.serviceAccount.automountServiceAccountToken=false unless the backup pod must call the Kubernetes API; AWS identity injection uses a separate projected token.

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.

Security and observability boundaries

The chart configures the main StatefulSet containers to run as non-root with dropped capabilities, and can configure TLS, structured pg_hba.conf rules, External Secrets, and NetworkPolicies. Operators still own certificate issuance, SecretStore configuration, credential rotation, backup encryption, and restrictive client and replication CIDRs. NetworkPolicy enforcement requires a compatible cluster network plugin, and the official PostgreSQL image keeps a writable runtime filesystem.

Metrics and ServiceMonitor resources are optional and require an existing Prometheus stack. The chart does not install Prometheus, log collection, dashboards, tracing, or alert rules. Production operators should alert on connection saturation, replication lag, retained WAL, storage growth, backup freshness, restore tests, and credential expiry.

Known limitations

Replication provides a fixed primary and read replicas; it does not perform promotion, fencing, failback, or automatic read/write routing. The backup CronJob creates logical dumps and does not provide continuous archiving or point-in-time recovery. Major PostgreSQL upgrades, storage migrations, connection pooling, and reconfiguration after a primary failure require external workflows or an operator.

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

On Kubernetes 1.26, a Delete PVC retention policy requires the StatefulSetAutoDeletePVC feature gate on both the API server and controller manager. Verify that cluster setting before relying on automatic deletion.

Service

Metrics

Backup

NetworkPolicy

Pod Disruption Budget

Service Account

Probes

Scheduling and Security

Extra

External Secrets Operator

Upgrade Notes

Preserve the values file used for the release and upgrade it explicitly:

helm upgrade my-pg helmforge/postgresql -n <namespace> -f values.yaml
kubectl rollout status statefulset/my-pg-postgresql -n <namespace>

Existing StatefulSets, Services, Secrets, and PVCs retain their Kubernetes identity when resource names are unchanged. Generated passwords are looked up and reused during live Helm upgrades. Do not use --reset-values unless returning to chart defaults is intentional, and never change the image major version without a PostgreSQL migration plan.

PostgreSQL 18.6 is the August 2026 security and bug-fix release; upstream did not publish 18.5 because of a post-wrap regression. Back up the cluster and review the official PostgreSQL 18.6 release notes before upgrading. A dump and restore is not required from an earlier PostgreSQL 18 release, but test extensions, authentication, replication, and application queries in staging.

• 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