Merge pull request #970 from EnterpriseDB/release/2021-02-22

Release/2021 02 22

Former-commit-id: 79759d0

.gitignore

@@ -80,3 +80,4 @@ product_docs/content/*
 !product_docs/content/.keep
 product_docs/content_build/*
 !product_docs/content_build/.keep
+temp_kubernetes/build/*

advocacy_docs/kubernetes/cloud_native_operator/architecture.mdx

@@ -0,0 +1,118 @@
+---
+title: 'Architecture'
+originalFilePath: 'src/architecture.md'
+---
+
+
+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
+    * `-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
+
+## Read-write workloads
+
+Applications can decide to connect to the PostgreSQL instance elected as *current primary*
+by the Kubernetes operator, as depicted in the following diagram:
+
+![Applications writing to the single primary](./images/architecture-rw.png)
+
+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
+purposes.
+
+## Read-only workloads
+
+!!! Important
+    Applications must be aware of the limitations that [Hot Standby](https://www.postgresql.org/docs/current/hot-standby.html)
+    presents and familiar with the way PostgreSQL operates when dealing with these workloads.
+
+Applications can access any PostgreSQL instance at any time through the `-r`
+service made available by the operator at connection time.
+
+The following diagram shows the architecture:
+
+![Applications reading from any instance in round robin](./images/architecture-r.png)
+
+## Application deployments
+
+Applications are supposed to work with the services created by Cloud Native PostgreSQL
+in the same Kubernetes cluster:
+
+* `[cluster name]-rw`
+* `[cluster name]-r`
+
+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](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies).
+
+!!! Hint
+    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.
+
+!!! Warning
+    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.
+
+## DNS resolution
+
+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
+full qualifier: `service-name.namespace-name`.
+
+DNS is the preferred and recommended discovery method.
+
+## Environment variables
+
+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 `pg-database`,
+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_RW_SERVICE_HOST`: the IP address of the
+  service pointing to the *primary* instance of the cluster
+
+## Secrets
+
+The PostgreSQL operator will generate two secrets for every PostgreSQL cluster
+it deploys:
+
+* `[cluster name]-superuser`
+* `[cluster name]-app`
+
+The secrets contain the username, password, and a working
+[`.pgpass file`](https://www.postgresql.org/docs/current/libpq-pgpass.html)
+respectively for the `postgres` user and the *owner* of the database.
+
+The `-app` credentials are the ones that should be used by applications
+connecting to the PostgreSQL cluster.
+
+The `-superuser` ones are supposed to be used only for administrative purposes.