#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>).

#Services and external access

Every cluster gets three ClusterIP services:

These services are always ClusterIP. Do not change their type with kubectl edit/patch: the change is not declared anywhere and is lost whenever the service is recreated (for example after a restore). To reach the database with a different service type (NodePort, LoadBalancer), declare an additional service in the Cluster:

spec:
  managed:
    services:
      disabledDefaultServices: ["ro", "r"]   # optional; rw cannot be disabled
      additional:
        - selectorType: rw                   # rw | ro | r
          updateStrategy: patch              # default; or replace
          serviceTemplate:
            metadata:
              name: pg-demo-rw-nodeport      # must not be <cluster>-rw/-ro/-r
              annotations: {}                # optional, e.g. load-balancer settings
            spec:
              type: NodePort                 # or LoadBalancer
              ports:                         # optional; only to pin the nodePort
                - name: postgres
                  port: 5432
                  targetPort: 5432
                  nodePort: 30432

• The operator owns the service selector (from selectorType), so do not set spec.selector. The service follows the primary across failover and switchover.
• Editing serviceTemplate changes the live service, including its type. Removing an entry from additional deletes that service.
• updateStrategy: patch (default) applies only the fields you changed in the template since the last reconcile. It does not revert out-of-band edits to the live service. Example: change type to ClusterIP and back to NodePort while keeping a pinned nodePort. The service comes back with a random port, and the operator reports no error. Use updateStrategy: replace to force the live service to match the template exactly. replace deletes and recreates the service on every change, so connections through that service are briefly interrupted and the ClusterIP/nodePort may change unless pinned.
• A LoadBalancer service needs a load-balancer implementation in the cluster; without one, EXTERNAL-IP stays <pending>.
• The admission webhook rejects disabling rw, reusing a reserved <cluster>-rw/-ro/-r name, and duplicate service names.
• Exposing PostgreSQL outside the cluster widens its attack surface. Restrict clients with pg_hba and, for LoadBalancer, spec.loadBalancerSourceRanges.

#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

#Trademark Notice

CloudNativePG™ is a trademark of The Linux Foundation.

PostgreSQL® is a registered trademark of the PostgreSQL Community Association of Canada.

Alauda is an independent vendor. This product is not affiliated with, endorsed by, or sponsored by The Linux Foundation, PostgreSQL Community Association of Canada. All trademarks are the property of their respective owners and are used here for identification purposes only.