#Configuration

How to configure a CloudNativePG Cluster on Alauda Container Platform: PostgreSQL parameters, users and databases, replication, storage, and images. For first deployment see the Quick Start; for the architecture see Architecture.

#PostgreSQL parameters

spec:
  postgresql:
    parameters:
      shared_buffers: 512MB
      max_connections: "200"
      work_mem: 8MB
    pg_hba:
      - host all all 10.0.0.0/8 scram-sha-256

• A set of parameters is operator-controlled and rejected if set (archive_mode, archive_command, restore_command, port, hot_standby, ssl*, synchronous_standby_names, shared_preload_libraries, recovery targets, listen/log/file-path settings). Use the dedicated fields instead: spec.postgresql.shared_preload_libraries, spec.postgresql.synchronous (below).
• Commonly tuned parameters (max_connections, shared_buffers, work_mem, effective_cache_size, autovacuum and checkpoint settings, …) are all allowed.
• The operator injects sensible defaults, including wal_level=logical, archive_timeout=5min, wal_keep_size=512MB, and TLS ≥ 1.3.
• ALTER SYSTEM is disabled by default (spec.postgresql.enableAlterSystem) — configuration is declarative; changes roll through the cluster governed by spec.primaryUpdateStrategy (unsupervised default) and spec.primaryUpdateMethod (restart or switchover).
• pg_hba entries are inserted between operator-managed fixed rules (local peer access, certificate-authenticated replication) and a trailing default of host all all all scram-sha-256.

#Users and databases

The bootstrap database and owner come from spec.bootstrap.initdb (defaults: database app, owner app, credentials in the <cluster>-app secret). Additional roles are declarative:

spec:
  managed:
    roles:
      - name: alice
        ensure: present
        login: true          # managed roles default to login: false
        createdb: true
        passwordSecret:
          name: alice-creds  # kubernetes.io/basic-auth secret

Additional databases are their own Database resources:

apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: pg-demo-reporting
spec:
  cluster:
    name: pg-demo
  name: reporting
  owner: alice
  extensions:
    - name: vector        # pgvector

Superuser access is disabled by default; enable with spec.enableSuperuserAccess: true (creates the <cluster>-superuser secret).

#Extensions and pgaudit

The standard PostgreSQL operands bundle pgvector, pgaudit, PostGIS, zhparser, TimescaleDB (Apache-2 OSS, PG 15+), and pg_failover_slots — all available without the Kubernetes ImageVolume feature gate.

Most extensions are enabled per-database with a Database resource (spec.extensions, see above) or a plain CREATE EXTENSION. Two are load-time extensions and must be declared via spec.postgresql.shared_preload_libraries (the bare shared_preload_libraries GUC is operator-controlled and rejected):

spec:
  postgresql:
    shared_preload_libraries:
      - pgaudit
      - pg_failover_slots
      - timescaledb        # PG 15+ only
    parameters:
      pgaudit.log: "ddl, write"   # configure pgaudit declaratively

• pgaudit must be configured declaratively. It is an operator-managed extension: a manual CREATE EXTENSION pgaudit is dropped on the next restart. Add pgaudit to shared_preload_libraries and set pgaudit.* parameters as above — the operator creates and maintains the extension for you.
• pg_failover_slots is preload-only by design (no CREATE EXTENSION step): once in shared_preload_libraries it synchronizes logical replication slots to standbys automatically.
• timescaledb requires shared_preload_libraries and is available on PG 15–18 only (no OSS package for PG 14 on Debian trixie). Only the Apache-2 edition is shipped — TSL features (compression, continuous aggregates) are not included.

#Replication and high availability

spec:
  instances: 3
  postgresql:
    synchronous:                 # optional synchronous replication
      method: any
      number: 1
      dataDurability: required   # 'preferred' favors availability
  affinity:
    podAntiAffinityType: required   # default 'preferred'
    topologyKey: kubernetes.io/hostname

Failover is automatic (the operator promotes the most advanced replica). Manual switchover is available through the cnpg kubectl plugin (kubectl cnpg promote <cluster> <instance>).

#Storage

spec:
  storage:
    size: 10Gi                  # grow in place by raising it (no shrink)
    storageClass: sc-topolvm    # use a TopoLVM class for production
  walStorage:                   # optional dedicated WAL volume
    size: 5Gi
    storageClass: sc-topolvm

Tablespaces are supported via spec.tablespaces (each gets its own PVC).

#Images and upgrades

Operand images default to the version shipped with the operator bundle. To pin explicitly, set spec.imageName to a PostgreSQL operand image from your platform registry — always use an immutable tag. Minor version updates are rolling restarts; major upgrades are declarative (change the image major; the cluster performs an offline upgrade). See Upgrade.

#IPv6 note

On single-stack IPv6 clusters, operator versions without the upstream url.Build bracket fix (upstream PR #10682) cannot reach instance managers over bare IPv6 pod IPs. Dual-stack clusters are unaffected. Consult the release notes of your operator version.

#Troubleshooting quick reference