Customize PostgreSQL cluster config and pod settings

PGO exposes a broad set of configuration knobs that let you tune PostgreSQL server parameters, control how pods are scheduled onto nodes, inject custom containers, and run SQL at cluster initialization. This guide walks through the most common customizations using real spec fields.

PostgreSQL server parameters

Use spec.config.parameters to set values in postgresql.conf. The field accepts a map of parameter names to values. PGO applies these to the running cluster; some parameters are reloaded live while others require a PostgreSQL restart.

spec:
  config:
    parameters:
      max_connections: "200"
      shared_buffers: 256MB
      work_mem: 4MB
      log_min_duration_statement: "1000"
      wal_level: logical

The parameters map accepts up to 50 entries. Several parameters are reserved and will be rejected by validation: listen_addresses, port, ssl, hot_standby, wal_log_hints, archive_mode, archive_command, restore_command, synchronous_standby_names, primary_conninfo, primary_slot_name, logging_collector, cluster_name, and paths like config_file, data_directory, hba_file, ident_file, external_pid_file. Use spec.port to change the PostgreSQL port.

Mount custom configuration files

Use spec.config.files to mount projected volumes into /etc/postgres. This is useful for providing pg_hba.conf fragments or other configuration files that PostgreSQL reads from that directory.

spec:
  config:
    files:
      - configMap:
          name: my-pg-config
          items:
            - key: custom.conf
              path: custom.conf

Run SQL after cluster initialization

spec.databaseInitSQL lets you run arbitrary SQL against the cluster after it has been initialized. You provide a ConfigMap in the same namespace, specifying which key holds the SQL string.

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-init-sql
data:
  init.sql: |
    CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
    CREATE SCHEMA IF NOT EXISTS app;
    GRANT USAGE ON SCHEMA app TO appuser;

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

The DatabaseInitSQL status field on the cluster reflects whether initialization has been applied.

The initialization SQL runs once after cluster bootstrap. It does not re-run on subsequent reconciliations unless the referenced ConfigMap content changes and the status is reset.

Custom container image and pull secrets

Specify a custom PostgreSQL image with spec.image. When omitted, the operator uses the environment variable RELATED_IMAGE_POSTGRES_{postgresVersion}.

spec:
  postgresVersion: 16
  image: my-registry.example.com/crunchy-postgres:ubi8-16.3-custom
  imagePullPolicy: IfNotPresent
  imagePullSecrets:
    - name: my-registry-secret

imagePullSecrets accepts a list of LocalObjectReference values. Changing this value causes all running pods to restart.

Pod scheduling constraints

Each instance set supports the full set of Kubernetes scheduling primitives. These are set directly on the instance set and cause a rolling restart when changed.

Node selector and affinity

spec:
  instances:
    - name: instance1
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: topology.kubernetes.io/zone
                    operator: In
                    values:
                      - us-east-1a
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                topologyKey: kubernetes.io/hostname
                labelSelector:
                  matchLabels:
                    postgres-operator.crunchydata.com/cluster: hippo

Tolerations

spec:
  instances:
    - name: instance1
      tolerations:
        - key: dedicated
          operator: Equal
          value: postgres
          effect: NoSchedule

Topology spread constraints

spec:
  instances:
    - name: instance1
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              postgres-operator.crunchydata.com/cluster: hippo

Disable default scheduling

By default, PGO applies scheduling constraints to spread pods across nodes. To rely entirely on your own constraints, set spec.disableDefaultPodScheduling: true.

spec:
  disableDefaultPodScheduling: true

Custom sidecars

The InstanceSidecars feature gate (alpha, enabled by default) allows you to add custom sidecar containers to instance pods via spec.instances[].containers.

spec:
  instances:
    - name: instance1
      containers:
        - name: my-sidecar
          image: my-registry.example.com/my-sidecar:latest
          resources:
            requests:
              cpu: 50m
              memory: 64Mi

Changing the containers field causes PostgreSQL to restart.

There is also a PGBouncerSidecars feature gate (alpha, disabled by default) for adding custom sidecars to pgBouncer pods. See Feature Gates.

Metadata labels and annotations

Use spec.metadata to apply additional labels and annotations to all resources that PGO manages for this cluster. This is useful for cost allocation, policy enforcement, or integrating with external tooling.

spec:
  metadata:
    labels:
      environment: production
      team: platform
    annotations:
      iam.amazonaws.com/role: arn:aws:iam::123456789012:role/postgres-role

You can also apply metadata at the instance set level using spec.instances[].metadata:

spec:
  instances:
    - name: instance1
      metadata:
        labels:
          tier: primary-set

Get Started

Installation

Core Operations

Day-Two Operations

Security

Customize PostgreSQL cluster config and pod settings

PostgreSQL server parameters

Mount custom configuration files

Run SQL after cluster initialization

Custom container image and pull secrets

Pod scheduling constraints

Node selector and affinity

Tolerations

Topology spread constraints

Disable default scheduling

Custom sidecars

Metadata labels and annotations

Next steps

Use tablespaces

PostgresCluster reference

​PostgreSQL server parameters

​Mount custom configuration files

​Run SQL after cluster initialization

​Custom container image and pull secrets

​Pod scheduling constraints

​Node selector and affinity

​Tolerations

​Topology spread constraints

​Disable default scheduling

​Custom sidecars

​Metadata labels and annotations

​Next steps

Use tablespaces

PostgresCluster reference

PostgreSQL server parameters

Mount custom configuration files

Run SQL after cluster initialization

Custom container image and pull secrets

Pod scheduling constraints

Node selector and affinity

Tolerations

Topology spread constraints

Disable default scheduling

Custom sidecars

Metadata labels and annotations

Next steps