Architecture

For High Availability and Scalability goals, the PostgreSQL database managementsystem provides administrators with built-in physicalreplication capabilities based on WriteAheadLog(WAL)shipping .

PostgreSQL supports both asynchronous and synchronous streaming replicationover the network, as well as asynchronous file-based log shipping (normallyused as a fallback option, for example, to store WAL files in an object store).Replicas are usually called standby servers and can also be used forread-only workloads, thanks to the Hot Standby feature.

CloudNativePG supports clusters based on asynchronous and synchronousstreaming replication to manage multiple hot standby replicas within the sameKubernetes cluster, with the following specifications:

Read-write workloads

Applications can decide to connect to the PostgreSQL instance elected ascurrent primary by the Kubernetes operator, as depicted in the followingdiagram:

Applications writing to the single primary

Applications can use the -rw suffix service.

In case of temporary or permanent unavailability of the primary, Kuberneteswill move the -rw service to another instance of the cluster for high availabilitypurposes.

Read-only workloads

Important

Applications must be aware of the limitations that Hot Standby presents and familiar with the way PostgreSQL operates when dealing with these workloads.

Applications can access hot standby replicas through the -ro service made availableby the operator. This service enables the application to offload read-only queries from theprimary node.

The following diagram shows the architecture:

Applications reading from hot standby replicas in round robin

Applications can also access any PostgreSQL instance through the -r service.

Multi-cluster deployments

Note

CloudNativePG supports deploying PostgreSQL across multiple Kubernetes clusters through a feature called Replica Cluster, which is described in this section.

In a distributed PostgreSQL cluster there can only be a single PostgreSQLinstance acting as a primary at all times. This means that applications canonly write inside a single Kubernetes cluster, at any time.

Tip

If you are interested in a PostgreSQL architecture where all instances accept writes, please take a look at BDR (Bi-Directional Replication) by EDB . For Kubernetes, BDR will have its own Operator, expected later in 2022.

However, for business continuity objectives it is fundamental to:

In order to address the above concerns, CloudNativePG introduces theconcept of a PostgreSQL Replica Cluster. Replica clusters are theCloudNativePG way to enable multi-cluster deployments in private, public,hybrid, and multi-cloud contexts.

A replica cluster is a separate Cluster resource:

1. having either pg_basebackup or full recovery as the bootstrap option from a defined external source cluster2. having the replica.enabled option set to true 3. replicating from a defined external cluster identified by replica.source , normally located outside the Kubernetes cluster4. replaying WAL information received from the recovery object store (using PostgreSQL’s restore_command parameter), or via streaming replication (using PostgreSQL’s primary_conninfo parameter), or any of the two (in case both the barmanObjectStore and connectionParameters are defined in the external cluster)5. accepting only read connections, as supported by PostgreSQL’s Hot Standby

See also

Please refer to the BootstrapConfiguration for more information about cloning a PostgreSQL cluster from another one (defined in the externalClusters section).

The diagram below depicts a PostgreSQL cluster spanning over two differentKubernetes clusters, where the primary cluster is in the first Kubernetescluster and the replica cluster is in the second. The second Kubernetes clusteracts as the company’s disaster recovery cluster, ready to be activated in caseof disaster and unavailability of the first one.

An example of multi-cluster deployment with a primary and a replica cluster

A replica cluster can have the same architecture of the primary cluster. Inplace of the primary instance, a replica cluster has a designatedprimary instance, which is a standby server with an arbitrary number of cascadingstandby servers in streaming replication (symmetric architecture).

The designated primary can be promoted at any time, making the replica clustera primary cluster capable of accepting write connections.

Warning

CloudNativePG does not perform any cross-cluster switchover or failover at the moment. Such operation must be performed manually or delegated to a multi-cluster/federated cluster aware authority. Each PostgreSQL cluster is independent from any other.

The designated primary in the above example is fed via WAL streaming( primary_conninfo ), with fallback option for file-based WAL shipping throughthe restore_command and barman-cloud-wal-restore .

CloudNativePG allows you to define multiple replica clusters.You can also define replica clusters with a lower number of replicas, and thenincrease this number when the cluster is promoted to primary.