Create and configure a PostgresCluster in Kubernetes

The PostgresCluster custom resource is the single source of truth for every aspect of a PGO-managed database cluster. When you apply a manifest, the operator reconciles all Kubernetes objects — StatefulSets, Services, Secrets, CronJobs — needed to match the declared state. This page walks through each key section of the spec so you can confidently provision and tune a cluster.

Minimal cluster

The smallest valid cluster requires a postgresVersion, at least one instance set with a dataVolumeClaimSpec, and a backup repository.

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
spec:
  postgresVersion: 16
  instances:
    - name: instance1
      dataVolumeClaimSpec:
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 10Gi
  backups:
    pgbackrest:
      repos:
        - name: repo1
          volume:
            volumeClaimSpec:
              accessModes:
                - "ReadWriteOnce"
              resources:
                requests:
                  storage: 10Gi

Apply the manifest and watch the cluster come up:

kubectl apply -f postgres.yaml
kubectl get postgrescluster hippo --watch

Once the cluster is ready, retrieve the connection URI from the auto-generated user secret:

kubectl get secret hippo-pguser-hippo \
  -o jsonpath='{.data.uri}' | base64 -d

Key spec fields

`postgresVersion`

Specifies the PostgreSQL major version to install. Accepted values are 11 through 18.

spec:
  postgresVersion: 16

To upgrade a running cluster to a new major version, use the PGUpgrade custom resource rather than editing postgresVersion in place. See the update Postgres guide.

`instances`

The instances list defines one or more instance sets. Each set maps to a Kubernetes StatefulSet. All instances share the same data through streaming replication orchestrated by Patroni.

Field	Required	Description
`name`	No (auto-assigned)	Unique name for the instance set within this cluster
`replicas`	No (default: `1`)	Number of PostgreSQL pods in this set
`dataVolumeClaimSpec`	Yes	PVC spec for the PostgreSQL data directory
`walVolumeClaimSpec`	No	Separate PVC for the write-ahead log
`resources`	No	CPU and memory requests and limits for the Postgres container
`affinity`	No	Pod scheduling affinity rules
`tolerations`	No	Pod tolerations
`topologySpreadConstraints`	No	Pod topology spread constraints

spec:
  instances:
    - name: instance1
      replicas: 3
      dataVolumeClaimSpec:
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 50Gi
      walVolumeClaimSpec:
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 10Gi

`backups.pgbackrest.repos`

At least one repo is required. Repositories can be PVC-backed volumes or cloud object storage. Repo names must follow the pattern repo1 through repo4. See the backups guide for cloud storage options.

Setting resource requests and limits

Set CPU and memory constraints on instance pods through instances[*].resources. The operator passes this directly to the Postgres container spec.

spec:
  instances:
    - name: instance1
      replicas: 2
      dataVolumeClaimSpec:
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 50Gi
      resources:
        requests:
          cpu: "500m"
          memory: "1Gi"
        limits:
          cpu: "2"
          memory: "4Gi"

Always set both requests and limits in production so the Kubernetes scheduler can place pods predictably and so Postgres is protected from noisy neighbors.

Custom Postgres configuration parameters

Use spec.config.parameters to set any tunable PostgreSQL parameter. Values are applied to postgresql.conf and reloaded when possible; some parameters require a server restart.

spec:
  config:
    parameters:
      max_connections: "200"
      shared_buffers: "512MB"
      work_mem: "16MB"
      maintenance_work_mem: "128MB"
      effective_cache_size: "2GB"
      log_min_duration_statement: "1000"

The operator rejects certain parameters that it manages directly, such as listen_addresses, port, ssl, archive_mode, hot_standby, and synchronous_standby_names. Attempting to set these results in a validation error.

Separate WAL volume

For workloads with heavy write throughput, placing the write-ahead log on its own PVC (and ideally a faster storage class) reduces I/O contention on the data volume.

spec:
  instances:
    - name: instance1
      dataVolumeClaimSpec:
        storageClassName: fast-nvme
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 100Gi
      walVolumeClaimSpec:
        storageClassName: fast-nvme
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 20Gi

Pulling from a private registry

Set spec.imagePullSecrets to a list of Kubernetes Secret names that hold Docker credentials. This applies to all containers in the cluster, including pgBackRest and pgBouncer.

spec:
  imagePullSecrets:
    - name: my-registry-credentials
  image: registry.example.com/crunchy-postgres:ubi8-16.3-0
  postgresVersion: 16
  instances:
    - name: instance1
      dataVolumeClaimSpec:
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 10Gi
  backups:
    pgbackrest:
      image: registry.example.com/crunchy-pgbackrest:ubi8-2.51-0
      repos:
        - name: repo1
          volume:
            volumeClaimSpec:
              accessModes:
                - "ReadWriteOnce"
              resources:
                requests:
                  storage: 10Gi

Changing imagePullSecrets causes all running pods to restart so they can pick up the new pull credentials.

Defining users and databases

By default, PGO creates one user and one database that match the cluster name. Use spec.users to declare additional users and the databases they can access.

spec:
  users:
    - name: app
      databases:
        - appdb
      options: "CREATEDB"
    - name: readonly
      databases:
        - appdb

PGO creates a Secret for each user — <cluster>-pguser-<username> — containing the connection string, host, port, database, username, and password.

Running initialization SQL

spec.databaseInitSQL points to a ConfigMap whose data key contains SQL to run once after the cluster is first initialized. This is useful for creating schemas, extensions, or seed data.

# configmap-init.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-init-sql
data:
  init.sql: |
    CREATE EXTENSION IF NOT EXISTS pgcrypto;
    CREATE SCHEMA IF NOT EXISTS app;

spec:
  databaseInitSQL:
    name: cluster-init-sql
    key: init.sql

Verifying the cluster

# Check overall cluster status
kubectl get postgrescluster hippo

# View instance pods
kubectl get pods -l postgres-operator.crunchydata.com/cluster=hippo

# Describe conditions and events
kubectl describe postgrescluster hippo

High availability

Configure multiple replicas and automatic failover with Patroni.

Backups

Set up scheduled backups to S3, GCS, Azure, or local volumes.

Connection pooling

Add pgBouncer to efficiently manage application connections.

Custom Resource Reference

Full field-by-field reference for the PostgresCluster CRD.

Get Started

Installation

Core Operations

Day-Two Operations

Security

Create and configure a PostgresCluster in Kubernetes

Minimal cluster

Key spec fields

`postgresVersion`

`instances`

`backups.pgbackrest.repos`

Setting resource requests and limits

Custom Postgres configuration parameters

Separate WAL volume

Pulling from a private registry

Defining users and databases

Running initialization SQL

Verifying the cluster

High availability

Backups

Connection pooling

Custom Resource Reference

​Minimal cluster

​Key spec fields

​postgresVersion

​instances

​backups.pgbackrest.repos

​Setting resource requests and limits

​Custom Postgres configuration parameters

​Separate WAL volume

​Pulling from a private registry

​Defining users and databases

​Running initialization SQL

​Verifying the cluster

High availability

Backups

Connection pooling

Custom Resource Reference

Minimal cluster

Key spec fields

`postgresVersion`

`instances`

`backups.pgbackrest.repos`

Setting resource requests and limits

Custom Postgres configuration parameters

Separate WAL volume

Pulling from a private registry

Defining users and databases

Running initialization SQL

Verifying the cluster