PostgreSQL

Overview

PostgreSQL is a widely used open-source relational database. This template deploys one PostgreSQL 18 server on a persistent volume, an optional PgBouncer connection pooler in front of it, and an optional cron job that writes compressed pg_dumpall backups to AWS S3, Google Cloud Storage or a MinIO (S3-compatible) bucket. Database credentials are not template values. The server reads its username, password and database name from a dictionary secret you create before installing, so no password passes through Helm or lands in the release. The template creates no secret of its own.

This template deploys into an existing GVC that you already have. It does not create or manage a GVC.

This is a single server, not a cluster — there is no replication or failover. For an automatically failing-over cluster in one location use PostgreSQL Highly Available; to span regions use Postgres Multi Location.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-postgres`	PostgreSQL 18 server (stateful, 1 replica, TCP `5432`)	—
Volume Set	`RELEASE_NAME-pg-vs`	`PGDATA` on an `ext4` general-purpose SSD volume; a final snapshot is taken when the volume set is deleted and kept 7 days	—
Identity	`RELEASE_NAME-pg-identity`	Shared by the database, pooler and backup workloads; carries the cloud account binding when backups use AWS or GCP	—
Policy	`RELEASE_NAME-pg-policy`	Grants the identity `reveal` on exactly the credential secrets you created	—
Workload	`RELEASE_NAME-pgbouncer`	PgBouncer connection pooler (serverless, TCP `5432`)	`pgbouncer.enabled: true`
Workload	`RELEASE_NAME-postgres-backup`	Scheduled `pg_dumpall` to S3, GCS or MinIO (cron)	`backup.enabled: true`

Prerequisites

One secret must exist before you install. It holds the credentials your applications put in their connection strings. Secrets are org-level, so no GVC flag is involved.

Create the database credentials secret

A dictionary secret holding exactly three keys — username, password and database. PostgreSQL creates that user (as a superuser) and that database the first time the volume is initialized:

cpln secret create-dictionary --name SECRET_NAME \
  --entry username=postgres \
  --entry password='YOUR-STRONG-PASSWORD' \
  --entry database=mydb

Set config.credentialsSecretName to this name. Read it back later with cpln secret reveal SECRET_NAME -o yaml — a bare cpln secret reveal prints only a summary table, not the values.

Create the secret before installing, or the deployment wedges silently. A config.credentialsSecretName that points at a secret which does not exist installs successfully and then never starts. The container never runs, so cpln logs returns zero lines. The one place the reason appears is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-postgres --gvc GVC_NAME -o yaml

The secret SECRET_NAME no longer exists. Workload updates are paused until the
secret is added or the reference to the secret removed.

Use get-deployments — plain cpln workload get has no versions key. Creating the missing secret repairs the deployment on its own within several minutes, or run cpln workload force-redeployment RELEASE_NAME-postgres --gvc GVC_NAME to skip the wait.

Backups are optional and need a bucket plus, for AWS or GCP, a Control Plane cloud account — see Backing Up. Nothing else is required for a default install.

Installation

Install the chart from the marketplace registry, pointing it at the secret you created:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/postgres \
  --version 3.4.1 --gvc GVC_NAME \
  --set config.credentialsSecretName=SECRET_NAME

Or 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

Each block below is the shipped default for that part of values.yaml.

Server and Resources

image: postgres:18  # versions before postgres:17 are compatible but do not support backup feature

resources:
  minCpu: 200m
  minMemory: 128Mi
  maxCpu: 500m
  maxMemory: 256Mi

On a stateful workload the ratio of maxCpu to minCpu may not exceed 4:1. Raising maxCpu without raising minCpu can cross that limit and is rejected when the workload is applied.

Credentials

config:
  # REQUIRED PREREQUISITE SECRET — CREATE IT BEFORE YOU INSTALL.
  # A `dictionary` secret holding exactly three keys: `username`, `password` and
  # `database`. If it does not exist at install time the deployment WEDGES
  # silently — `cpln logs` returns nothing at all. See Prerequisites in the README
  # for the exact `cpln secret create-dictionary` command.
  credentialsSecretName: my-postgres-credentials

The three keys are applied only when the volume is first initialized. Changing the secret afterwards does not change the stored password — see Rotating the Password.

Storage

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false # Set to true to enable autoscaling
    maxCapacity: 100 # Maximum capacity in GiB when autoscaling is enabled
    minFreePercentage: 10 # Minimum free percentage to trigger scaling when autoscaling is enabled
    scalingFactor: 1.2 # Scaling factor to determine how much to scale up when autoscaling is triggered

Internal Access

internalAccess: # Sets the internal firewall scope - if set to none, replicas will not be able to reach each other
  type: same-gvc # options: none, 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
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

Type	Who can reach port `5432`
`none`	No workload
`same-gvc`	Every workload in the same GVC
`same-org`	Every workload in the same org
`workload-list`	Only the workloads listed in `internalAccess.workloads`

The same setting applies to the PgBouncer workload when it is enabled. A change to internalAccess can take several minutes to take effect — re-test before concluding it did not apply.

PgBouncer

PgBouncer multiplexes many application connections into a small pool of real database connections. When enabled it becomes the endpoint your applications connect to, and it reads the same credentials secret and identity as the server — nothing extra to configure.

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
  maxClientConn: 1000   # maximum number of client connections PgBouncer accepts
  replicas: 1

  resources:
    cpu: 200m
    memory: 128Mi

`poolMode`	Behaviour
`transaction`	The server connection is held for one transaction. Best for most web and API workloads; not compatible with `SET` variables, temporary tables or advisory locks.
`session`	Held for the whole client session. Compatible with everything, less reuse — raise `defaultPoolSize` to your expected concurrency.
`statement`	Returned after every statement. Transactions are not supported.

Backup

A cron workload runs pg_dumpall on the schedule and uploads a gzip-compressed SQL dump of every database and role to the bucket for the chosen provider. It authenticates with the username and password from your credentials secret. Each provider’s bucket, cloud account and policy steps are under Backing Up.

backup: # compatible with Postgres 17+
  enabled: false
  image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0 # tag 18.1.0 = Postgres 18, 17.1.0 = Postgres 17
  schedule: "0 2 * * *"   # daily at 2am UTC

  resources:
    cpu: 100m
    memory: 128Mi

  provider: aws # Options: aws, gcp, or minio

  aws:
    bucket: my-postgres-bucket
    region: us-east-1
    cloudAccountName: my-s3-cloud-account
    policyName: my-postgres-backup-policy # bucket-scoped IAM policy, see README
    prefix: postgres/backups # folder name where your backups will be stored

  gcp:
    bucket: my-postgres-bucket
    cloudAccountName: my-gcs-cloud-account
    prefix: postgres/backups # folder name where your backups will be stored

  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: my-postgres-bucket
    # REQUIRED PREREQUISITE SECRET when provider is `minio` — a `dictionary`
    # secret holding `accessKey` and `secretKey`. See Storage setup in the README.
    credentialsSecretName: my-postgres-minio-credentials
    prefix: postgres/backups # folder name where your backups will be stored

Backups require PostgreSQL 17 or later, and backup.image must match the server’s major version: tag 18.1.0 for postgres:18, 17.1.0 for postgres:17.

Connecting

This template exposes no public endpoint. Everything below is reachable from inside the GVC, subject to internalAccess.type.

What	Address	Notes
PostgreSQL, direct	`RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432`	Always available.
PostgreSQL, pooled	`RELEASE_NAME-pgbouncer.GVC_NAME.cpln.local:5432`	Only when `pgbouncer.enabled: true`. Prefer it when the pooler is on.
Credentials	`cpln secret reveal SECRET_NAME -o yaml`	The `username`, `password` and `database` keys. Never stored in the Helm release.

To verify from your own machine, tunnel to the server and connect with psql:

cpln port-forward RELEASE_NAME-postgres 5432:5432 --gvc GVC_NAME

psql "postgresql://USERNAME:PASSWORD@127.0.0.1:5432/DATABASE" -c 'select version()'

Or run psql inside the container, where the credentials are already present as environment variables:

cpln workload exec RELEASE_NAME-postgres --gvc GVC_NAME --container postgresql -- psql -U USERNAME -d DATABASE -c 'select version()'

Operations

Backing Up

Backups are off by default. Enable them with backup.enabled: true, pick a backup.provider, and complete that provider’s setup below first. The job writes postgres-TIMESTAMP.sql.gz objects under backup.PROVIDER.prefix in your bucket on every run of backup.schedule.

The AWS S3 and MinIO paths have been exercised end to end, including downloading a dump and restoring it. The GCS path renders and binds correctly but has not been exercised the same way — rehearse a backup and restore before relying on it.

Backup Prerequisites

Complete the steps for your provider before enabling backups.

AWS S3

Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.
If you do not have one yet, create a Control Plane cloud account for the AWS account holding the bucket. Set backup.aws.cloudAccountName to its name.
Create an IAM policy scoped to exactly that bucket, replacing YOUR_BUCKET_NAME:

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

Set backup.aws.policyName to that policy’s name. The template attaches it to the workload identity and nothing else — the bucket in your policy is the only storage the backup job can reach.

GCS

Create a GCS bucket. Set backup.gcp.bucket to its name.
Create a Control Plane cloud account for the GCP project holding the bucket, and set backup.gcp.cloudAccountName to its name.
Grant the cloud account’s service account the Storage Admin (roles/storage.admin) role. The template additionally binds the identity to roles/storage.objectAdmin on exactly the bucket in backup.gcp.bucket.

MinIO

No cloud account is needed — the job authenticates with a second prerequisite secret.

Create the bucket in MinIO. Set backup.minio.bucket to its name.
Set backup.minio.endpoint to the S3 API address including the port. For the minio template deployed in the same GVC that is http://WORKLOAD_NAME.GVC_NAME.cpln.local:9000.
Create a dictionary secret holding exactly the keys accessKey and secretKey, and set backup.minio.credentialsSecretName to its name. For the minio template these are its admin username and password:

cpln secret create-dictionary --name SECRET_NAME \
  --entry accessKey=MINIO_ACCESS_KEY \
  --entry secretKey=MINIO_SECRET_KEY

The policy this template creates grants the identity reveal on this secret as well as the database credentials secret, and on nothing else.

Restoring a Backup

Each backup is a gzip-compressed pg_dumpall script, so it is restored by connecting to the postgres maintenance database as the superuser from your credentials secret; the script recreates the roles and databases it contains. Run the commands from a client that can reach both the bucket and the server — a workload inside the GVC, or your own machine with cpln port-forward RELEASE_NAME-postgres 5432:5432 --gvc GVC_NAME open and --host=127.0.0.1 in place of the internal hostname.

AWS S3
GCS
MinIO

export PGPASSWORD="PASSWORD"

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

unset PGPASSWORD

export PGPASSWORD="PASSWORD"

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

unset PGPASSWORD

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/postgres-TIMESTAMP.sql.gz" - --endpoint-url "http://MINIO_ENDPOINT:9000" \
  | gunzip \
  | psql \
      --host=RELEASE_NAME-postgres.GVC_NAME.cpln.local \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

already exists errors for the role and database that the server created at first boot are expected; the rest of the script loads normally. Restore into an empty database (a fresh install, or one whose databases you have dropped) to avoid duplicate-object errors on existing tables.

Rotating the Password

The server reads the secret only when the volume is first initialized, so change the password inside PostgreSQL first, then update the secret to match:

ALTER ROLE USERNAME WITH PASSWORD 'NEW-STRONG-PASSWORD';

Workloads resolve the secret when a replica starts, so an updated secret is not picked up by a running replica. The backup job reads it fresh on its next scheduled run; if PgBouncer is enabled, force a redeployment so it reconnects with the new password:

cpln workload force-redeployment RELEASE_NAME-pgbouncer --gvc GVC_NAME

Upgrading From Earlier Versions

Template versions up to 3.3.0 took the database credentials as plain Helm values with a working default password, and wrote them into a chart-owned secret named after the release. Version 3.4.0 removed both, and an upgrade that still carries the old keys is refused at render — your existing release is left running rather than restarted against a different password.

	3.3.0 and earlier	3.4.0 and later
Database credentials	`config.username`, `config.password`, `config.database` values	`config.credentialsSecretName` → a dictionary secret you create
Credential secret	`RELEASE_NAME-pg-config`, created by the chart	Not created — credentials live only in your secret
MinIO backup credentials	`backup.minio.accessKey`, `backup.minio.secretKey` values	`backup.minio.credentialsSecretName` → a dictionary secret you create
Backup identity permissions	Bucket-scoped policy plus `aws::ReadOnlyAccess`	Bucket-scoped policy only — no action needed, backups keep working
`backup.schedule`	Any cron beginning with `*` failed to render	Accepts every cron form, including `/15 * * *`

Read the credentials the database already uses

An existing database keeps the credentials it was initialized with. Recover them from your current values file, or from the secret the old version created — before upgrading:

cpln secret reveal RELEASE_NAME-pg-config -o yaml

Create the prerequisite secret with those same values

Follow Prerequisites using the existing username, password and database. Different values here do not change the database — they only leave the workload unable to authenticate.

Remove the old keys from your values

Delete config.username, config.password and config.database, and set config.credentialsSecretName to your secret’s name. If you back up to MinIO, replace backup.minio.accessKey and backup.minio.secretKey with backup.minio.credentialsSecretName.

Upgrade, then rotate any default password

After the upgrade succeeds, change any password that came from a 3.3.x default — those defaults were published in the public template repository, so treat them as compromised. Follow Rotating the Password.

The chart no longer creates RELEASE_NAME-pg-config. Anything outside this release that referenced that secret by name — another workload’s environment, a policy, or a parent chart that bundles PostgreSQL as a subchart — must be pointed at the secret you created instead. A reference to a secret that no longer exists does not fail loudly; it wedges the referring workload silently, exactly as described in Prerequisites.

Scaling and Availability

The server is pinned to one replica. Do not raise it — a single volume set backs a single server, and a second replica cannot mount it. Choose PostgreSQL Highly Available or Postgres Multi Location when you need failover.
PgBouncer is stateless; pgbouncer.replicas scales it horizontally for high connection counts.
Every cpln helm upgrade restarts the server, including the first upgrade after an install even when nothing changed. Plan each one as a short write outage.
A node failure reschedules the server and reattaches the same volume. The exposure is minutes of downtime, not data loss. The volume set is not snapshotted on a schedule — it takes one final snapshot when it is deleted, kept for seven days — so use the backup job for point-in-time copies.

Troubleshooting

Workload never becomes ready and cpln logs returns nothing

Symptom: the install succeeds, the workload stays not ready indefinitely, and cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-postgres"}' --limit 50 --since 10m returns zero lines.Cause: config.credentialsSecretName names a secret that does not exist, so the container is never started. The message is only visible in status.versions[].message:

cpln workload get-deployments RELEASE_NAME-postgres --gvc GVC_NAME -o yaml

The secret SECRET_NAME no longer exists. Workload updates are paused until the
secret is added or the reference to the secret removed.

Fix: create the secret as in Prerequisites. The deployment recovers on its own within several minutes, or run cpln workload force-redeployment RELEASE_NAME-postgres --gvc GVC_NAME.

Upgrade fails with 'config.username was REMOVED in postgres 3.4.0'

Symptom: cpln helm upgrade stops before touching any resource:

Error: execution error at (postgres/templates/workload-postgres.yaml:1:4): config.username was
REMOVED in postgres 3.4.0. Database credentials are no longer values: create a `dictionary` secret
holding the keys `username`, `password` and `database`, and set config.credentialsSecretName to its
name. See Prerequisites in the README.

config.password, config.database, and backup.minio.accessKey / backup.minio.secretKey each produce the same kind of message under their own name.Cause: your values still carry keys that were removed in 3.4.0.Fix: follow Upgrading From Earlier Versions. Your running release is unaffected until the upgrade succeeds.

Password changed in the secret but the old one still works

Symptom: you updated the password key in the credentials secret, but PostgreSQL still accepts the previous password and rejects the new one.Cause: the secret is applied only when the volume is first initialized. Afterwards the stored password lives in the database, not the secret.Fix: change it inside PostgreSQL and then update the secret to match — see Rotating the Password.

PgBouncer admin console rejects the database user with 'FATAL: not allowed'

Symptom: psql -d pgbouncer against the pooler fails with FATAL: not allowed.Cause: the PgBouncer image restricts its admin console to the postgres user. This is upstream behaviour, not a template setting.Fix: connect to your application database through the pooler as normal; use the admin console only if your credentials secret’s username is postgres.

Apply rejected with 'The ratio between cpu and minCpu must be less than 4:1'

Symptom: an install or upgrade fails and the server workload is not created or updated.Cause: resources.maxCpu is more than four times resources.minCpu, which the platform rejects on a stateful workload.Fix: raise resources.minCpu or lower resources.maxCpu so the ratio is at most 4:1.

Important Notes

Create the credentials secret before installing. A reference to a secret that does not exist wedges the workload with no log output; see Prerequisites for the one command that shows the reason.
Credentials are read only when the volume is first initialized. Rotate with ALTER ROLE inside PostgreSQL, then update the secret — see Rotating the Password.
Do not scale the server past one replica. It is a single instance on a single volume, not a replicated cluster.
cpln helm uninstall deletes the volume set and the database with it. Your credentials secret is yours and is left alone.
Every cpln helm upgrade restarts the server. Treat each one as a short planned write outage.
Upgrading from 3.3.0 or earlier is a breaking change — the removed keys stop the upgrade rather than resetting a password. See Upgrading From Earlier Versions.

External References

PostgreSQL Documentation

Official PostgreSQL documentation

PostgreSQL Backup and Restore

Upstream guidance on pg_dumpall dumps and restores

PgBouncer Documentation

PgBouncer configuration reference

Backup Image Source

Source for the PostgreSQL backup container image

PostgreSQL Template

Source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Server and Resources

Credentials

Storage

Internal Access

PgBouncer

Backup

Connecting

Operations

Backing Up

Backup Prerequisites

AWS S3

GCS

MinIO

Restoring a Backup

Rotating the Password

Upgrading From Earlier Versions

Scaling and Availability

Troubleshooting

Important Notes

External References

PostgreSQL Documentation

PostgreSQL Backup and Restore

PgBouncer Documentation

Backup Image Source

PostgreSQL Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Server and Resources

​Credentials

​Storage

​Internal Access

​PgBouncer

​Backup

​Connecting

​Operations

​Backing Up

​Backup Prerequisites

​AWS S3

​GCS

​MinIO

​Restoring a Backup

​Rotating the Password

​Upgrading From Earlier Versions

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

PostgreSQL Documentation

PostgreSQL Backup and Restore

PgBouncer Documentation

Backup Image Source

PostgreSQL Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Server and Resources

Credentials

Storage

Internal Access

PgBouncer

Backup

Connecting

Operations

Backing Up

Backup Prerequisites

AWS S3

GCS

MinIO

Restoring a Backup

Rotating the Password

Upgrading From Earlier Versions

Scaling and Availability

Troubleshooting

Important Notes

External References