#Architecture

Reference: CloudNativePG Project Documentation.

Alauda build of CloudNativePG packages the upstream CNPG operator with mirror-registry images and ACP-aligned RBAC. The architecture below applies to both upstream and Alauda distributions; ACP-specific additions are called out where relevant.

#Core Components

1. Operator Controller (cnpg-controller-manager)

   • Single Deployment in the cnpg-system namespace, watches all namespaces (AllNamespaces install mode).
   • Reconciles CNPG Custom Resources: Cluster, Backup, ScheduledBackup, Pooler, Database, Publication, Subscription, ImageCatalog, ClusterImageCatalog.
   • Handles cluster lifecycle: create, scale, configuration updates, primary promotion on failover, rolling upgrade of PG pods.
   • Kubernetes-native: unlike older operators that wrap Patroni and depend on a separate distributed consensus store (etcd, ZooKeeper), CNPG implements primary/standby coordination using only Kubernetes primitives (Leases, Endpoints).

2. Instance Manager (in-pod sidecar)

   • One per PostgreSQL pod, communicates with the operator via gRPC.
   • Owns local PostgreSQL lifecycle: starts/stops the server, applies configuration, manages WAL archive.
   • Reports instance state (recovery mode, replication lag, disk usage) back to the operator.
   • Eliminates the need for a separate Patroni process and its etcd dependency.

3. PostgreSQL Container Image

   • Alauda distribution: build-harbor.alauda.cn/middleware/cnpg/postgresql:<MM.mm>-{minimal,standard}-trixie for PostgreSQL 14, 15, 16, 17, 18.
   • Upstream-equivalent: ghcr.io/cloudnative-pg/postgresql:<MM.mm>-{system,minimal,standard}-trixie.
   • Standard variant: includes pgaudit, pgvector, pg-failover-slots, postgis (where supported).
   • Minimal variant: bare PostgreSQL only; suitable when extensions are layered separately.
   • Both variants ship multi-architecture (amd64 + arm64).

4. Pooler / PgBouncer

   • Optional Pooler CR creates a PgBouncer Deployment in front of a Cluster.
   • Image: build-harbor.alauda.cn/middleware/cnpg/pgbouncer:1.25.1.
   • Modes: session, transaction, statement. Backed by upstream PgBouncer.

5. Barman Cloud Plugin (separate sibling package, post-Alpha)

   • CNPG-I plugin for object-storage backup with pgBackRest semantics.
   • Ships as cloudnative-pg-barman-cloud-plugin ACP package; not bundled with the operator package.

#CRD Landscape

#Cluster Topology

A Cluster CR with instances: 3 produces:

cluster-example-1     (primary, accepts writes)
cluster-example-2     (replica, streaming from primary)
cluster-example-3     (replica, streaming from primary)

Each instance is an independent StatefulSet-style Pod with its own PVC. There is no shared storage; replication is streaming WAL.

Three Services are auto-created:

#High Availability and Failover

• Primary election: the operator elects the primary at startup and on failover. The election uses Kubernetes Lease objects for distributed coordination.
• Failover trigger: pod loss, node loss, replication lag exceeding threshold, or operator-initiated switchover via cluster.spec.targetPrimary.
• Failover time: typically single-digit seconds. The operator detects primary failure via instance manager heartbeat, promotes a replica via pg_promote, and updates the <cluster>-rw Service endpoint to redirect traffic.
• Synchronous replication: configurable via spec.minSyncReplicas and spec.maxSyncReplicas to require N standbys to acknowledge each write before it's accepted as durable.
• No split-brain: the operator's promotion logic is consensus-based at the K8s API layer; no second primary can be promoted while the original is still considered alive.

#Storage Model

• One PVC per instance, named <cluster>-N for instance N.
• Storage class is set per-Cluster via spec.storage.storageClass (no cluster-default fallback in CNPG).
• Volume size is set via spec.storage.size.
• Reclaim policy: Delete is typical for ephemeral test clusters; Retain is recommended for production. Set on the StorageClass itself.
• WAL archiving: separate spec.walStorage block (optional) routes WAL to a different volume/StorageClass for performance isolation.

#Image Catalog Model

ImageCatalog and ClusterImageCatalog CRs let cluster operators centralize PostgreSQL image versions:

apiVersion: postgresql.cnpg.io/v1
kind: ClusterImageCatalog
metadata:
  name: postgresql
spec:
  images:
    - major: 14
      image: build-harbor.alauda.cn/middleware/cnpg/postgresql:14.22-standard-trixie
    - major: 18
      image: build-harbor.alauda.cn/middleware/cnpg/postgresql:18.3-standard-trixie

A Cluster can then reference the catalog by major version:

spec:
  imageCatalogRef:
    apiGroup: postgresql.cnpg.io
    kind: ClusterImageCatalog
    name: postgresql
    major: 18

This decouples Cluster CR specs from concrete image tags, simplifying fleet-wide PostgreSQL upgrades.

#ACP RBAC Architecture

Alauda build of CloudNativePG bundles a five-role L5 RBAC family wired into the ACP namespace-admin / namespace-developer aggregation chain:

Each role has a public shell ClusterRole (carries the ACP target-role aggregation labels) and one or more base ClusterRoles (carry the actual rules). Both labels (target-role + scope) must be present on the base role for ACP's AND-matcher aggregation to kick in. Cluster-scoped resources (ClusterImageCatalog) live in dedicated cluster-scope:*-base ClusterRoles.

#Comparison: Alauda CNPG vs Alauda PostgreSQL (Zalando-track)

The two operators are independent and can co-exist on the same cluster (different namespaces, different CRD groups). Migration between them is via logical replication or backup/restore, not in-place.