PostgresCluster CRD field reference (v1beta1)

The PostgresCluster custom resource is the primary API for PGO. It defines a complete, production-grade PostgreSQL cluster including instance sets, backup repositories, connection pooling, monitoring, and high availability. PGO continuously reconciles the cluster to match the desired state you declare in this resource. API group: postgres-operator.crunchydata.com/v1beta1 Kind: PostgresCluster Scope: Namespaced

Example

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
spec:
  postgresVersion: 16
  instances:
    - name: instance1
      replicas: 2
      dataVolumeClaimSpec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 10Gi
  backups:
    pgbackrest:
      repos:
        - name: repo1
          schedules:
            full: "0 1 * * *"
          volume:
            volumeClaimSpec:
              accessModes:
                - ReadWriteOnce
              resources:
                requests:
                  storage: 10Gi
  proxy:
    pgBouncer:
      replicas: 2
  monitoring:
    pgmonitor:
      exporter: {}
  users:
    - name: myapp
      databases:
        - myappdb

The apiVersion must be postgres-operator.crunchydata.com/v1beta1. The example in the PGO source repository uses postgres-operator.crunchydata.com/v1 — always use v1beta1 for current deployments.

Spec fields

integer

required

The major version of PostgreSQL to run. Accepted values: 11 through 18.

postgresVersion: 16

[]InstanceSpec

required

One or more sets of PostgreSQL pods that replicate data for this cluster. At least one instance set must be defined. Each set is backed by a StatefulSet. Multiple instance sets allow you to place replicas on different node pools or availability zones.

Show instance set properties

string

Unique name for this instance set within the cluster. Optional when only one instance set is defined. The combined length of the cluster name and this value must be 46 characters or less. Defaults to a zero-padded index (e.g. 00).Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?)?$

integer

Number of PostgreSQL pods in this instance set. Default: 1. Minimum: 1.

VolumeClaimSpec

required

PersistentVolumeClaim definition for the PostgreSQL data directory (PGDATA). Must include at least one accessMode and a storage request.

dataVolumeClaimSpec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: fast-ssd

Show autoGrow properties

integer

Percentage of used space at which to trigger volume expansion. Default: 75. Range: 50–90. Requires a storage limit set on the PVC.

quantity

Maximum size to which the volume can be automatically expanded. When not set, the volume grows by 50% each time the trigger is exceeded.

VolumeClaimSpec

Optional separate PersistentVolumeClaim for PostgreSQL’s write-ahead log (WAL). Separating WAL onto its own volume can improve I/O performance on high-write workloads.

ResourceRequirements

Compute resource requests and limits for the PostgreSQL container.

resources:
  requests:
    cpu: "1"
    memory: 2Gi
  limits:
    cpu: "4"
    memory: 8Gi

Affinity

Kubernetes affinity and anti-affinity rules for scheduling PostgreSQL pods. Changing this value causes PostgreSQL to restart.

[]Toleration

Tolerations for scheduling PostgreSQL pods onto tainted nodes. Changing this value causes PostgreSQL to restart.

[]TopologySpreadConstraint

Topology spread constraints for distributing PostgreSQL pods across zones or nodes. Changing this value causes PostgreSQL to restart.

string

Priority class name for the PostgreSQL pod. Changing this value causes PostgreSQL to restart.

integer or string

Minimum number of pods that should be available at a time. Defaults to one when replicas is greater than one.

[]Container

Custom sidecar containers to add to PostgreSQL instance pods. Changing this value causes PostgreSQL to restart.

InstanceSidecars

Configuration for managed sidecar containers. Supports replicaCertCopy sidecar resource configuration.

[]TablespaceVolume

List of tablespace volumes to mount. Each entry requires a name (lowercase alphanumeric, starting with a letter) and a dataVolumeClaimSpec. Requires the TablespaceVolumes feature gate to be enabled. See feature gates.

PostgresVolumesSpec

Additional volumes to add to instance pods.

Show volumes properties

[]AdditionalVolume

Up to 10 additional pre-existing PVC or OCI image volumes. Each entry requires a name and either a claimName or image. Volumes are mounted at /volumes/{name} in containers.

VolumeClaimSpec

An ephemeral volume for temporary files.

Metadata

Labels and annotations to apply to pods and other resources created for this instance set.

Backups

PostgreSQL backup configuration. Contains the pgbackrest archive configuration and optional snapshots configuration.

Show backups.pgbackrest properties

[]PGBackRestRepo

required

List of pgBackRest repositories. At least one repository is required. Each repository must have a unique name matching the pattern ^repo[1-4] (i.e. repo1, repo2, repo3, or repo4). Exactly one storage type must be specified per repo.

Show repo properties

string

required

Repository name. Must match ^repo[1-4].

PGBackRestBackupSchedules

Cron schedules for automated backups. Supports full, differential, and incremental backup types.

schedules:
  full: "0 1 * * 0"        # Every Sunday at 01:00
  differential: "0 1 * * 1-6"  # Mon–Sat at 01:00
  incremental: "0 */4 * * *"   # Every 4 hours

RepoPVC

PVC-backed repository. When at least one volume repo is defined, a dedicated repository host Deployment is created.

volume:
  volumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 20Gi

RepoS3

AWS S3 or S3-compatible repository. Requires bucket, endpoint, and region.

RepoGCS

Google Cloud Storage repository. Requires bucket.

RepoAzure

Azure Blob Storage repository. Requires container.

map[string]string

Global pgBackRest configuration settings. These are merged into the [global] section of the generated pgBackRest configuration, mounted at /etc/pgbackrest/conf.d.

[]VolumeProjection

Projected volumes containing custom pgBackRest configuration files. Files are mounted at /etc/pgbackrest/conf.d.

string

Container image for pgBackRest. Defaults to the RELATED_IMAGE_PGBACKREST operator environment variable.

PGBackRestRepoHost

Configuration for the dedicated pgBackRest repository host Deployment. Only applicable when at least one PVC-based repository is defined.

Show repoHost properties

Affinity

Scheduling affinity for the repo host pod.

[]Toleration

Tolerations for the repo host pod.

ResourceRequirements

Compute resources for the repo host container.

string

Priority class name for the repo host pod.

[]TopologySpreadConstraint

Topology spread constraints for the repo host pod.

PGBackRestManualBackup

Trigger a manual (unscheduled) backup. Set repoName to the target repo and add the annotation postgres-operator.crunchydata.com/pgbackrest-backup with a unique ID to initiate.

manual:
  repoName: repo1
  options:
    - --type=full

PGBackRestRestore

In-place restore configuration. Set enabled: true along with repoName and optional options to trigger a restore. Requires the cluster to be paused first.

In-place restores overwrite the existing cluster data. Always verify your backup before initiating a restore.

BackupJobs

Resource configuration applied to all backup Job pods (manual, scheduled, and replica-create backups).

Show jobs properties

ResourceRequirements

Compute resources for backup Job containers.

Affinity

Scheduling affinity for backup Job pods.

[]Toleration

Tolerations for backup Job pods.

string

Priority class name for backup Job pods.

integer

Lifetime of finished backup Jobs before automatic cleanup. Minimum: 60.

PGBackRestSidecars

Resource configuration for managed pgBackRest sidecar containers (pgbackrest and pgbackrestConfig).

Show backups.snapshots properties

string

required

Name of the VolumeSnapshotClass to use for volume snapshot backups.

PostgresProxySpec

Configuration for the connection pooler that sits in front of PostgreSQL. Currently supports pgBouncer.

Show proxy.pgBouncer properties

integer

Number of pgBouncer pods. Default: 1. Minimum: 0.

integer

Port on which pgBouncer listens for client connections. Default: 5432. Minimum: 1024.

string

Container image for pgBouncer 1.15 or newer. Defaults to the RELATED_IMAGE_PGBOUNCER operator environment variable.

PGBouncerConfiguration

pgBouncer configuration settings. Changes are automatically reloaded without validation.

Show config properties

map[string]string

Process-wide pgBouncer settings (the [pgbouncer] section). Maximum 50 properties.

map[string]string

Database connection string definitions (the [databases] section). When empty, a single * entry connects to the primary PostgreSQL instance.

map[string]string

Per-user connection settings (the [users] section).

[]VolumeProjection

Files to mount under /etc/pgbouncer. Settings in pgbouncer.ini are loaded first. Changes to references cause pgBouncer to restart; changes to file contents are automatically reloaded.

ServiceSpec

Service definition for the pgBouncer endpoint. Defaults to ClusterIP.

Show service properties

string

Service type: ClusterIP, NodePort, or LoadBalancer. Default: ClusterIP.

integer

Node port to use when type is NodePort or LoadBalancer.

string

IP family policy: SingleStack, PreferDualStack, or RequireDualStack.

ResourceRequirements

Compute resources for pgBouncer containers. Changing this value causes pgBouncer to restart.

Affinity

Scheduling affinity for pgBouncer pods. Changing this value causes pgBouncer to restart.

[]Toleration

Tolerations for pgBouncer pods. Changing this value causes pgBouncer to restart.

[]TopologySpreadConstraint

Topology spread constraints for pgBouncer pods. Changing this value causes pgBouncer to restart.

SecretProjection

Secret projection containing a tls.crt, tls.key, and ca.crt for encrypting connections to pgBouncer. Changing this value causes pgBouncer to restart.

integer or string

Minimum number of pgBouncer pods available at a time. Defaults to one when replicas is greater than one.

[]Container

Custom sidecar containers for pgBouncer pods. Changing this value causes pgBouncer to restart.

Metadata

Labels and annotations to apply to pgBouncer pods and services.

See the connection pooling guide for practical pgBouncer configuration examples.

MonitoringSpec

Configuration for PostgreSQL monitoring tools.

Show monitoring.pgmonitor properties

ExporterSpec

Configuration for the crunchy-postgres-exporter sidecar, which exposes Prometheus-compatible metrics.

Show exporter properties

string

Container image for the exporter. Defaults to the RELATED_IMAGE_PGEXPORTER operator environment variable.

ResourceRequirements

Compute resources for the exporter container. Changing this value causes PostgreSQL and the exporter to restart.

[]VolumeProjection

Custom exporter configuration volumes. If a queries.yml file is detected, it is loaded via the --extend.query-path flag. Changing this value causes PostgreSQL and the exporter to restart.

SecretProjection

Secret containing TLS certificates to encrypt the exporter web server output.

DataSource

Bootstrap the cluster data directory from an existing backup or cluster. Only one data source can be specified at a time.

Show dataSource properties

PGBackRestDataSource

Bootstrap from a cloud-based pgBackRest repository (S3, GCS, or Azure). Incompatible with postgresCluster. Requires repo (without a volume type), stanza, and optional global settings and options.

PostgresClusterDataSource

Bootstrap from an existing PostgresCluster’s pgBackRest repository. Requires repoName. Defaults to the same cluster name and namespace if clusterName and clusterNamespace are omitted.

dataSource:
  postgresCluster:
    clusterName: old-hippo
    clusterNamespace: default
    repoName: repo1
    options:
      - --type=time
      - --target="2024-01-15 12:00:00"

DataSourceVolumes

Reuse existing PVCs from a previous cluster. Supports pgDataVolume, pgWALVolume, and pgBackRestVolume. Each requires a pvcName and an optional directory.

When reusing volumes, the pgWALVolume must be accompanied by pgDataVolume.

PostgresConfigSpec

General PostgreSQL server configuration.

Show config properties

map[string]IntOrString

PostgreSQL runtime parameters (from postgresql.conf). Keys are parameter names and values are their settings. Maximum 50 entries. Some values reload without restart; others require a restart. Some parameters cannot be changed.

config:
  parameters:
    max_connections: "200"
    shared_buffers: "512MB"
    log_min_duration_statement: "1000"
    work_mem: "16MB"

The following parameters are managed by PGO and cannot be set: listen_addresses, port, ssl, wal_log_hints, hot_standby, archive_mode, archive_command, logging_collector, cluster_name, and replication parameters. Setting wal_level is restricted to logical or higher.

[]VolumeProjection

Projected volumes mounted at /etc/postgres. Use this to supply custom configuration files that PostgreSQL can reference.

PostgresAuthenticationSpec

PostgreSQL host-based authentication (pg_hba.conf) rules. Rules are evaluated in order; the first match determines the authentication method. Connections matching no rule are rejected.When omitted or empty, PostgreSQL accepts encrypted network connections from users with a password.

Show authentication properties

[]PostgresHBARuleSpec

Up to 10 HBA rules. Each rule is either a raw hba string or a structured rule with connection and method fields (both required for structured rules).

authentication:
  rules:
    - connection: hostssl
      databases: [myapp]
      users: [myappuser]
      method: scram-sha-256
    - hba: "host all all 10.0.0.0/8 scram-sha-256"

See the authentication guide for common HBA configurations.

SecretProjection

Secret projection supplying a custom server TLS certificate for PostgreSQL connections. The secret must contain tls.crt, tls.key, and ca.crt keys.When provided, customReplicationTLSSecret must also be provided, and both secrets must share the same CA certificate.

See the TLS guide for instructions on bringing your own certificates.

SecretProjection

Secret projection supplying the replication client TLS certificate. Required when customTLSSecret is set. Must contain tls.crt, tls.key, and ca.crt keys with the same CA as customTLSSecret.

DatabaseInitSQL

A ConfigMap containing SQL to run once after the cluster is initialized. The ConfigMap must be in the same namespace as the cluster.

databaseInitSQL:
  name: my-init-sql
  key: init.sql

[]PostgresUserSpec

Users to create inside PostgreSQL and the databases they should access. Maximum 64 users. The default creates one user matching the cluster name with access to a database of the same name. An empty list creates no users.

Removing a user from this list does not drop the user or revoke their access in PostgreSQL.

users:
  - name: alice
    databases:
      - appdb
    options: "SUPERUSER"
    password:
      type: AlphaNumeric
  - name: readonly
    databases:
      - appdb

Show user properties

string

required

PostgreSQL username. Lowercase letters, numbers, and hyphens only. Maximum 63 characters.

[]string

Databases to which this user has connect and create-object privileges. This field is ignored for the postgres superuser.

string

ALTER ROLE options (excluding PASSWORD). Maximum 200 characters. Example: SUPERUSER CREATEDB.

PostgresPasswordSpec

Password generation settings. type is either ASCII (default, includes symbols) or AlphaNumeric (letters and numbers only).

PatroniSpec

Patroni high-availability configuration. Changes to dynamicConfiguration are automatically reloaded; other changes cause PostgreSQL to restart.

Show patroni properties

object

Patroni dynamic configuration settings. Passed directly to Patroni without validation. Changes are applied automatically. See Patroni docs.

integer

Duration of the cluster leader lock in seconds. Determines how long before automatic failover begins. Default: 30. Minimum: 3.

integer

Interval for refreshing the leader lock and applying dynamicConfiguration. Must be less than leaderLeaseDurationSeconds. Default: 10. Minimum: 1.

integer

Port on which Patroni listens for its REST API. Default: 8008. Minimum: 1024.

PatroniSwitchover

Trigger an ad-hoc switchover or failover.

Show switchover properties

boolean

required

Whether switchovers are permitted.

string

The pod name that should become primary. Required for Failover type; optional for Switchover.

string

Switchover (default) — changes the primary on a healthy cluster. Failover — forces a specific instance to become primary regardless of health.

PatroniLogConfig

Patroni log configuration.

Show logging properties

quantity

required

Maximum total space for Patroni log files. Minimum: 25Mi.

string

Patroni log level. One of: CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET. Default: INFO.

PostgresStandbySpec

Run this cluster as a read-only hot standby that follows another PostgreSQL server or pgBackRest repository.

standby:
  enabled: true
  repoName: repo1

Show standby properties

boolean

Whether the cluster should operate in standby mode. Default: true when the field is present.

string

Name of the pgBackRest repository to follow for WAL files. Pattern: ^repo[1-4].

string

Network address of the primary PostgreSQL server to follow via streaming replication.

integer

Network port of the primary PostgreSQL server. Minimum: 1024.

ServiceSpec

Specification of the Kubernetes Service that exposes the PostgreSQL primary instance.

service:
  type: LoadBalancer

ServiceSpec

Specification of the Kubernetes Service that exposes PostgreSQL replica instances.

UserInterfaceSpec

Configuration for a pgAdmin user interface deployed alongside this cluster. See also the standalone PGAdmin custom resource.

Show userInterface.pgAdmin properties

VolumeClaimSpec

required

PVC for pgAdmin data storage.

string

pgAdmin 4 container image.

integer

Number of pgAdmin pods. Default: 1. Range: 0–1.

ResourceRequirements

Compute resources for the pgAdmin container.

ServiceSpec

Service definition for pgAdmin. Defaults to ClusterIP.

PGAdminConfiguration

pgAdmin configuration including settings (key-value pairs mapping to config_py.html) and ldapBindPassword secret reference.

string

Container image for PostgreSQL. When omitted, the operator uses an environment variable named RELATED_IMAGE_POSTGRES_{postgresVersion} (e.g. RELATED_IMAGE_POSTGRES_16). For PostGIS images, the format is RELATED_IMAGE_POSTGRES_{version}_GIS_{postgisVersion}.

string

Image pull policy for all PostgreSQL containers. One of: Always, Never, IfNotPresent.

[]LocalObjectReference

Image pull secrets for pulling images from a private registry. Changing this value causes all running pods to restart.

imagePullSecrets:
  - name: my-registry-secret

string

PostGIS extension version installed in the PostgreSQL image. When image is not set, indicates that a PostGIS-enabled image should be used.

integer

Port on which PostgreSQL listens. Default: 5432. Minimum: 1024.

boolean

When true, disables the operator’s default pod scheduling constraints and uses only the custom constraints you provide. When false or unset, default constraints are applied in addition to any custom ones.

[]integer

Group IDs added to every container in the cluster. Useful when accessing shared file systems with restricted permissions. Values must be between 1 and 2147483647.

boolean

Whether the cluster is deployed in an OpenShift environment. When unset, the operator auto-detects the environment.

boolean

When true, suspends rollout and reconciliation of changes to the PostgresCluster spec. The cluster continues running but no spec changes are applied.

boolean

When true, scales all workloads to zero and suspends CronJobs. Services and Volumes remain in place. The cluster can be restarted by setting this to false.

InstrumentationSpec

Configuration for the OpenTelemetry collector container used to collect logs and metrics from all cluster pods.

Metadata

Labels and annotations to propagate to all resources created for this cluster.

metadata:
  labels:
    environment: production
    team: platform
  annotations:
    example.com/owner: platform-team

Status fields

PGO populates the following fields in status to reflect the observed state of the cluster.

Field	Type	Description
`status.instances`	`[]PostgresInstanceSetStatus`	Current state of each instance set, including `replicas`, `readyReplicas`, and `updatedReplicas`.
`status.patroni.systemIdentifier`	`string`	The PostgreSQL system identifier as reported by Patroni.
`status.pgbackrest.repos`	`[]RepoStatus`	Status of each pgBackRest repository, including `bound`, `stanzaCreated`, and `replicaCreateBackupComplete`.
`status.pgbackrest.repoHost.ready`	`boolean`	Whether the pgBackRest repository host is ready.
`status.pgbackrest.manualBackup`	`PGBackRestJobStatus`	Status of the most recent manual backup job.
`status.pgbackrest.scheduledBackups`	`[]PGBackRestScheduledBackupStatus`	Status of each scheduled backup CronJob.
`status.proxy.pgBouncer.readyReplicas`	`integer`	Number of ready pgBouncer pods.
`status.startupInstance`	`string`	The instance pod that should be started first when bootstrapping.
`status.startupInstanceSet`	`string`	The instance set associated with `startupInstance`.
`status.postgresVersion`	`integer`	The current PostgreSQL major version (updated after a successful major upgrade).
`status.databaseInitSQL`	`string`	State of custom database initialization.
`status.observedGeneration`	`integer`	The `.metadata.generation` on which the status was last based.
`status.conditions`	`[]Condition`	Standard Kubernetes conditions. Known types: `PersistentVolumeResizing`, `Progressing`, `ProxyAvailable`.

Custom Resources

Configuration

Troubleshooting

PostgresCluster CRD field reference (v1beta1)

Example

Spec fields

Status fields

​Example

​Spec fields

​Status fields

​Related guides

Example

Spec fields

Status fields

Related guides