#Architecture

Reference: CloudNativePG Project Documentation.

Alauda Data Services Relational Database E3 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: registry-dev.alauda.io/eco-oss/postgres/cnpg/pgbouncer:1.25.2-202610260735-trixie.
   • 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 Data Services Relational Database E3 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 Data Services Relational Database E3 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.

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