PostGIS

Deploy PostGIS on Control Plane using the Template Catalog. Covers the prerequisite credentials secret, volumes, internal access, scheduled S3 and GCS backups, and upgrading from template version 1.3.2.

Overview

PostGIS extends PostgreSQL with support for geographic objects and spatial queries, making it the standard choice for location-aware applications. This template deploys a single-replica PostGIS instance with persistent storage.

Database credentials are not template values. PostGIS 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.

Template version 1.4.0 is a breaking security change. config.username and config.password were removed, and an install or upgrade that still sets either one now fails at render instead of silently falling back to a published default password. If you are running 1.3.2 or earlier, read Upgrading From 1.3.2 or Earlier before you touch the release.

PostGIS on Control Plane operates as a single-replica deployment. Do not scale up the replica count, as this would result in multiple isolated instances rather than a replicated cluster.

What Gets Created

• Stateful PostGIS Workload — A single-replica PostGIS database container with configurable resources.
• Volume Set — Persistent storage for database data, with optional autoscaling.
• Backup Config Secret (optional) — A dictionary secret holding the backup bucket and region. Non-sensitive, and created only when backup.enabled: true.
• Identity & Policy — An identity bound to the workload, and a policy granting it reveal on exactly the credentials secret you created — plus the backup config secret and Cloud Account binding when backup is enabled.
• Backup Cron Workload (optional) — A scheduled pg_dump backup job that writes compressed SQL dumps to AWS S3 or GCS.

The template creates no credential secret of its own. The username, password and database name live only in the prerequisite secret described below.

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

Upgrading From 1.3.2 or Earlier

Template versions up to 1.3.2 took the database credentials as plain Helm values, shipped working defaults for them, and wrote those credentials into a chart-owned secret named after the release. Version 1.4.0 removes all of that.

	1.3.2 and earlier	1.4.0
Database credentials	config.username, config.password, config.database values	config.credentialsSecretName → a dictionary secret you create
Where the password lives	Chart-created secret RELEASE_NAME-postgis-config, and the Helm release	Only the secret you create

Carrying the old values forward stops the upgrade. The removed keys are rejected at render, so cpln helm upgrade fails and your existing release is left untouched and running, rather than quietly restarting against a different password:

Error: execution error at (postgis/templates/identity.yaml:1:4): postgis: config.username and
config.password were REMOVED — they are now a `dictionary` secret you create, named by
config.credentialsSecretName, holding the keys `username`, `password` and `database`. Delete
them from your values. See Prerequisites in the README.

1. Read the credentials the database already uses

   Credentials are written into the data directory the first time the volume is initialized, so an existing database keeps whatever it was created with. Recover them from your current values file, or from the secret the old version created — do this before upgrading:

   cpln secret reveal RELEASE_NAME-postgis-config -o yaml
   

   Pass -o yaml. A bare cpln secret reveal prints only a summary table, not the values.

2. Create the prerequisite secret with those same values

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

3. Remove the old keys from your values

   Delete config.username, config.password and config.database, and set config.credentialsSecretName to your secret’s name.

4. Upgrade, then rotate the password

   After the upgrade succeeds, change any password that came from a 1.3.2 default — those defaults were published in the public template repository, so treat them as compromised. Rotate inside PostGIS, then update the secret to match:

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

RELEASE_NAME-postgis-config no longer holds credentials. It is now created only when backup.enabled: true, and holds nothing but the backup destination. Anything outside this release that read the username or password from it by name — another workload’s environment, a policy, or a parent chart bundling PostGIS as a subchart — must be pointed at the secret you create instead. A reference to a key that no longer exists does not fail loudly; it wedges the referring workload silently.

Prerequisites

One secret must exist before you install. It holds the credentials your applications put in their connection strings. The values never pass through Helm, so they do not land in the release. Secrets are org-level, so no GVC flag is involved.

1. Create the database credentials secret

   A dictionary secret holding exactly three keys — username, password and database. PostGIS creates that role and that database on first boot:

   cpln secret create-dictionary --name my-postgis-credentials \
     --entry username=myuser \
     --entry password='YOUR-STRONG-PASSWORD' \
     --entry database=mydb
   

   Set config.credentialsSecretName to the name you used. Secret names are org-wide, so give each release its own.

2. Read the secret back later

   Pass -o yaml. A bare cpln secret reveal prints only a summary table, not the values:

   cpln secret reveal my-postgis-credentials -o yaml
   

Create the secret before installing, or the deployment wedges silently. The template refuses to render when config.credentialsSecretName is blank, but a name pointing at a secret that does not exist installs “successfully” and then never starts. The container never runs, so cpln logs returns zero lines — there is nothing to log, and every summary surface just looks like a slow deploy. The one place the reason appears is status.versions[].message:

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

The secret my-postgis-credentials 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 and will show you nothing. Creating the missing secret repairs it on its own with no further action, in roughly 5.5 to 10.5 minutes measured across five templates, or run cpln workload force-redeployment RELEASE_NAME-postgis --gvc GVC_NAME to clear it in about 90 seconds.

Backups need a bucket, and a Control Plane Cloud Account, before they can be enabled — see AWS S3 or GCS. Nothing else is required.

Installation

Create the prerequisite secret first, then install by whichever method you prefer:

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:

image: postgis/postgis:18-3.6

resources:
  minCpu: 200m
  minMemory: 528Mi
  maxCpu: 500m
  maxMemory: 1024Mi

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
  # for the exact `cpln secret create-dictionary` command.
  credentialsSecretName: my-postgis-credentials

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

backup: # compatible with PostGIS 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 or gcp

  aws:
    bucket: my-backup-bucket
    region: us-east-1
    cloudAccountName: my-backup-cloudaccount
    policyName: my-backup-policy
    prefix: postgis/backups

  gcp:
    bucket: my-backup-bucket
    cloudAccountName: my-backup-cloudaccount
    prefix: postgis/backups

internalAccess:
  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

Credentials

• config.credentialsSecretName — Name of the dictionary secret holding username, password and database. PostGIS creates that role and that database on first boot, with the PostGIS extension installed into it. These are the credentials your applications put in their connection strings.

The secret must exist before installing — see Prerequisites. The workload reads it through cpln://secret/... references, so the values appear in neither the Helm release nor the stored workload spec.

The credentials are applied only on first startup, when the data directory is empty. Changing the secret afterwards does not change the running database — it only changes what the workload presents when it authenticates, which will then fail. To rotate on an existing instance, run ALTER ROLE ... WITH PASSWORD inside PostgreSQL first, then update the secret to match.

Resources

• resources.minCpu / resources.minMemory — Minimum CPU and memory guaranteed to the workload.
• resources.maxCpu / resources.maxMemory — Maximum CPU and memory the workload can use.

Storage

• volumeset.capacity — Initial volume size in GiB (minimum 10).
• 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.

Internal Access

• internalAccess.type — Controls which workloads can connect to PostGIS on port 5432:

Type	Description
none	No internal access allowed
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

Connecting to PostGIS

Once deployed, connect to the database from within the same GVC using:

RELEASE_NAME-postgis.GVC_NAME.cpln.local:5432

Backup

Backup is disabled by default. When enabled, a cron workload runs pg_dump on the configured schedule and uploads compressed SQL dumps to AWS S3 or GCS.

Backup requires PostGIS 17 or later. Set backup.image to match your PostGIS version: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0 for PostGIS 18, or the 17.1.0 tag of the same image for PostGIS 17.

• backup.enabled — Enable scheduled backups.
• backup.schedule — Cron expression for backup frequency (default: daily at 2am UTC).
• backup.provider — aws or gcp.
• backup.resources.cpu / backup.resources.memory — Resources for the backup cron container.

AWS S3

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

1. Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.
2. 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.
3. Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME:

Version 1.4.1 narrows AWS backup permissions. This version removes aws::ReadOnlyAccess from the backup identity. That AWS managed policy granted read access to every bucket in your AWS account and contains no write actions at all, so it was never carrying the backup itself — but it was silently supplying any read action your own bucket-scoped policy happened to omit.

Update your IAM policy to the full action list below before upgrading. If it already matches, no action is needed. The identity now carries cpln-connector and your bucket-scoped policy only, which is strictly narrower than before. Nothing else changes.

{
    "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/*"
            ]
        }
    ]
}

4. Set backup.aws.policyName to the name of the policy created in step 3.
5. 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:

1. Create a GCS bucket. Set backup.gcp.bucket to its name.
2. 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.
3. Add the Storage Admin role to the GCP service account associated with the Cloud Account.
4. Set backup.gcp.prefix to the folder path where backups will be stored.

Restoring a Backup

Run the following from a client with access to the backup bucket:

AWS S3:

export PGPASSWORD="PASSWORD"

aws s3 cp "s3://BUCKET_NAME/PREFIX/BACKUP_FILE.sql.gz" - \
  | gunzip \
  | psql \
      --host=RELEASE_NAME-postgis.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-postgis.GVC_NAME.cpln.local \
      --port=5432 \
      --username=USERNAME \
      --dbname=postgres

unset PGPASSWORD

External References

PostGIS Documentation

Official PostGIS documentation

PostgreSQL Documentation

Official PostgreSQL documentation

Backup Image Source

Source code for the PostgreSQL backup container image

PostGIS Template

View the source files, default values, and chart definition