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.
TOC
PostgreSQL parametersUsers and databasesCredential SecretsApplication database and owner passwordSuperuser (postgres) passwordAdditional rolesAdditional databasesCreating a cluster from the ConsoleExtensions and pgauditReplication and high availabilityServices and external accessStorageImages and upgradesIPv6 noteTroubleshooting quick referenceTrademark NoticePostgreSQL parameters
- 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 SYSTEMis disabled by default (spec.postgresql.enableAlterSystem) — configuration is declarative; changes roll through the cluster governed byspec.primaryUpdateStrategy(unsuperviseddefault) andspec.primaryUpdateMethod(restartorswitchover).pg_hbaentries are inserted between operator-managed fixed rules (local peer access, certificate-authenticated replication) and a trailing default ofhost all all all scram-sha-256.
Users and databases
CloudNativePG never stores passwords inline in the Cluster resource.
Every password the operator applies comes from a Kubernetes Secret of
type kubernetes.io/basic-auth in the same namespace as the
cluster. You either let the operator generate those Secrets, or you
create them yourself and reference them by name.
Credential Secrets
A credential Secret you create yourself must:
- have
type: kubernetes.io/basic-authwith the keysusernameandpassword; - carry a
usernamethat exactly matches the PostgreSQL role it is used for (app/ theinitdb.owner,postgres, or the managed role name). A mismatch is rejected by the instance manager and the password is not applied; - carry the label
cnpg.io/reload: "true". The operator only watches Secrets with this label, so with the label a password change is applied to PostgreSQL immediately; without it the change is picked up only at a later, unrelated reconciliation. Secrets generated by the operator already carry this label.
With kubectl:
Or declaratively:
A Secret you create contains only username and password. Secrets the
operator generates (<cluster>-app, <cluster>-superuser) contain
ready-to-use connection details as well:
Application database and owner password
spec.bootstrap.initdb creates the application database and its
owner. By default the database is app, the owner is app, and the
operator generates the <cluster>-app Secret with a random password.
To choose the password when the cluster is created, create the
credential Secret first (see above — username must equal
spec.bootstrap.initdb.owner), then reference it:
spec.bootstrap.recovery.secret and spec.bootstrap.pg_basebackup.secret
accept an application-owner Secret in the same way when a cluster is
bootstrapped from a backup or cloned from another cluster.
Changing the password later: update the password key of the Secret
in use (<cluster>-app or the one referenced by initdb.secret). With
the cnpg.io/reload: "true" label, the instance manager runs
ALTER ROLE on the primary right away; clients must reconnect with the
new password.
Superuser (postgres) password
Superuser access over the network is disabled by default
(spec.enableSuperuserAccess: false): the operator sets the postgres
role's password to NULL and manages the instance through local peer
and TLS client-certificate authentication only.
-
Generated password: set
spec.enableSuperuserAccess: true. The operator creates the<cluster>-superuserSecret. -
Your own password: create a credential Secret with
username: postgres(and thecnpg.io/reload: "true"label), then set both fields:
spec.superuserSecret has no effect unless
spec.enableSuperuserAccess is true. With access disabled the operator
ignores the Secret's content and keeps the postgres password NULL;
setting enableSuperuserAccess back to false later also deletes the
operator-generated <cluster>-superuser Secret (a Secret you created
yourself is left in place).
Additional roles
Additional roles are declarative. Two forms are available and can be used side by side for different roles:
DatabaseRoleresources (recommended) — one resource per role, independent of theClustermanifest. Suited to GitOps and to letting application teams manage their own roles.spec.managed.roles— roles listed inline in theCluster.
DatabaseRole example — the resource, the referenced Cluster and the
password Secret must all be in the same namespace:
Equivalent inline form:
Points to keep in mind:
- Roles default to
login: false. Setlogin: truefor any role that clients connect with. - Without
passwordSecretthe role is created with aNULLpassword.disablePassword: trueexplicitly sets it toNULL; it cannot be combined withpasswordSecret. - Removing a role: inline roles use
ensure: absent. ADatabaseRoledoes not acceptensure; delete the resource instead, anddatabaseRoleReclaimPolicydecides what happens in PostgreSQL —retain(default) keeps the role,deleterunsDROP ROLE(which fails, and the resource staysTerminating, while the role still owns objects). - If the same role name is declared in both
spec.managed.rolesand aDatabaseRole,spec.managed.rolestakes precedence: theDatabaseRoleis not applied and reportsapplied: falsewithdatabase role is already managed by the CNPG cluster. - A
DatabaseRolepointed at a role that already exists adopts it and resets every attribute you omit (for example, memberships not ininRolesare revoked). The namespostgres,streaming_replica, and names starting withpg_orcnpg_are reserved. - Check progress with
kubectl get databaserole -n pg-demo(Appliedcolumn).
Additional databases
Additional databases are their own Database resources:
With databaseReclaimPolicy: delete, deleting the Database resource
also drops the database in PostgreSQL; with retain the database is
kept.
Creating a cluster from the Console
In the ACP Console (Data Services → CloudNativePG → Create),
the Form view creates the cluster with the defaults described above:
an app database and owner whose password is generated into the
<cluster>-app Secret, and no superuser password.
To set your own passwords at creation time (bootstrap.initdb.secret,
superuserSecret, or roles under managed.roles), first create the
kubernetes.io/basic-auth Secrets in the target namespace, then switch
the Create page to the YAML view and add the fields shown above — or
apply the manifest with kubectl. Generated passwords can be read from
the <cluster>-app / <cluster>-superuser Secrets at any time.
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):
pgauditmust be configured declaratively. It is an operator-managed extension: a manualCREATE EXTENSION pgauditis dropped on the next restart. Addpgaudittoshared_preload_librariesand setpgaudit.*parameters as above — the operator creates and maintains the extension for you.pg_failover_slotsis preload-only by design (noCREATE EXTENSIONstep): once inshared_preload_librariesit synchronizes logical replication slots to standbys automatically.timescaledbrequiresshared_preload_librariesand 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
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:
- The operator owns the service
selector(fromselectorType), so do not setspec.selector. The service follows the primary across failover and switchover. - Editing
serviceTemplatechanges the live service, including itstype. Removing an entry fromadditionaldeletes 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: changetypetoClusterIPand back toNodePortwhile keeping a pinnednodePort. The service comes back with a random port, and the operator reports no error. UseupdateStrategy: replaceto force the live service to match the template exactly.replacedeletes and recreates the service on every change, so connections through that service are briefly interrupted and theClusterIP/nodePortmay change unless pinned.- A
LoadBalancerservice needs a load-balancer implementation in the cluster; without one,EXTERNAL-IPstays<pending>. - The admission webhook rejects disabling
rw, reusing a reserved<cluster>-rw/-ro/-rname, and duplicate service names. - Exposing PostgreSQL outside the cluster widens its attack surface.
Restrict clients with
pg_hbaand, forLoadBalancer,spec.loadBalancerSourceRanges.
Storage
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.