For High Availability goals, the PostgreSQL database management system provides administrators with built-in physical replication capabilities based on Write Ahead Log (WAL) shipping.
PostgreSQL supports both asynchronous and synchronous streaming replication, as well as asynchronous file-based log shipping (normally used 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 for read-only workloads, thanks to the Hot Standby feature.
Cloud Native PostgreSQL currently supports clusters based on asynchronous and synchronous streaming replication to manage multiple hot standby replicas, with the following specifications:
- One primary, with optional multiple hot standby replicas for High Availability
- Available services for applications:
-rw: applications connect to the only primary instance of the cluster
-ro: applications connect to the only hot standby replicas for read-only-workloads
-r: applications connect to any of the instances for read-only workloads
- Shared-nothing architecture recommended for better resilience of the PostgreSQL cluster:
- PostgreSQL instances should reside on different Kubernetes worker nodes and share only the network
- PostgreSQL instances can reside in different availability zones in the same region
- All nodes of a PostgreSQL cluster should reside in the same region
Applications can decide to connect to the PostgreSQL instance elected as current primary by the Kubernetes operator, as depicted in the following diagram:
Applications can use the
-rw suffix service.
In case of temporary or permanent unavailability of the primary, Kubernetes
will move the
-rw to another instance of the cluster for high availability
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 available
by the operator. This service enables the application to offload read-only queries from the
The following diagram shows the architecture:
Applications can also access any PostgreSQL instance at any time through the
-r service at connection time.
Applications are supposed to work with the services created by Cloud Native PostgreSQL in the same Kubernetes cluster:
Those services are entirely managed by the Kubernetes cluster and implement a form of Virtual IP as described in the "Service" page of the Kubernetes Documentation.
It is highly recommended to use those services in your applications, and avoid connecting directly to a specific PostgreSQL instance, as the latter can change during the cluster lifetime.
You can use these services in your applications through:
- DNS resolution
- environment variables
As far as the credentials to connect to PostgreSQL are concerned, you can use the secrets generated by the operator.
The operator will create another service, named
[cluster name]-any. That
service is used internally to manage PostgreSQL instance discovery.
It's not supposed to be used directly by applications.
You can use the Kubernetes DNS service, which is required by this operator,
to point to a given server.
You can do that by just using the name of the service if the application is
deployed in the same namespace as the PostgreSQL cluster.
In case the PostgreSQL cluster resides in a different namespace, you can use the
DNS is the preferred and recommended discovery method.
If you deploy your application in the same namespace that contains the PostgreSQL cluster, you can also use environment variables to connect to the database.
For example, suppose that your PostgreSQL cluster is called
you can use the following environment variables in your applications:
PG_DATABASE_R_SERVICE_HOST: the IP address of the service pointing to all the PostgreSQL instances for read-only workloads
PG_DATABASE_RO_SERVICE_HOST: the IP address of the service pointing to all hot-standby replicas of the cluster
PG_DATABASE_RW_SERVICE_HOST: the IP address of the service pointing to the primary instance of the cluster
The PostgreSQL operator will generate two secrets for every PostgreSQL cluster it deploys:
The secrets contain the username, password, and a working
respectively for the
postgres user and the owner of the database.
-app credentials are the ones that should be used by applications
connecting to the PostgreSQL cluster.
-superuser ones are supposed to be used only for administrative purposes.