Merge pull request #6378 from EnterpriseDB/content/pg4k-pgd/v1.1.0

PG4K-PGD v1.1.0 import
EnterpriseDB · Dec 30, 2024 · 91ed0bf · 91ed0bf · github-actions · Dec 30, 2024
2 parents 8de4357 + 6633487
commit 91ed0bf
Show file tree

Hide file tree

Showing 45 changed files with 2,526 additions and 613 deletions.
diff --git a/product_docs/docs/postgres_distributed_for_kubernetes/1/architecture.mdx b/product_docs/docs/postgres_distributed_for_kubernetes/1/architecture.mdx
@@ -3,7 +3,7 @@ title: 'Architecture'
 originalFilePath: 'src/architecture.md'
 ---
 
-Consider these main architectural aspects 
+Consider these main architectural aspects
 when deploying EDB Postgres Distributed in Kubernetes.
 
 EDB Postgres Distributed for Kubernetes is a
@@ -13,7 +13,7 @@ running in private, public, hybrid, or multi-cloud environments.
 
 ## Relationship with EDB Postgres Distributed
 
-[EDB Postgres Distributed (PGD)](https://www.enterprisedb.com/docs/pgd/latest/)
+[EDB Postgres Distributed (PGD)](/pgd/latest/)
 is a multi-master implementation of Postgres designed for high performance and 
 availability.
 PGD generally requires deployment using
@@ -75,7 +75,7 @@ EDB Postgres Distributed for Kubernetes manages the following:
 
 PGD groups assume full mesh connectivity of PGD nodes. Each node must be able to
 connect to every other node using the appropriate connection string (a
-`libpq`-style DSN). Write operations don't need to be sent to every node. PGD 
+`libpq`-style DSN). Write operations don't need to be sent to every node. PGD
 takes care of replicating data after it's committed to one node.
 
 For performance, we often recommend sending write operations mostly to a
@@ -126,7 +126,7 @@ To function in Kubernetes, containers are provided for each Postgres
 distribution. These are the *operands*.
 In addition, the operator images are kept in those same repositories.
 
-See [EDB private image registries](identify_images/private_registries.md)
+See [EDB private image registries](private_edb_registries.md)
 for details on accessing the images.
 
 ### Kubernetes architecture
@@ -194,6 +194,6 @@ For more information, see ["Connectivity"](connectivity.md).
 
 !!! Note Regions and availability zones
 
-    When creating Kubernetes clusters in different regions or availability zones for cross-regional replication, 
-    ensure the clusters can communicate with each other by enabling network connectivity. Specifically, every service created with a `-node` or `-group` suffix must be discoverable by all other `-node` and `-group` services. You can achieve this by deploying a network connectivity application like 
-    [Submariner](https://submariner.io/) on every cluster. 
+    When creating Kubernetes clusters in different regions or availability zones for cross-regional replication,
+    ensure the clusters can communicate with each other by enabling network connectivity. Specifically, every service created with a `-node` or `-group` suffix must be discoverable by all other `-node` and `-group` services. You can achieve this by deploying a network connectivity application like
+    [Submariner](https://submariner.io/) on every cluster.
diff --git a/product_docs/docs/postgres_distributed_for_kubernetes/1/before_you_start.mdx b/product_docs/docs/postgres_distributed_for_kubernetes/1/before_you_start.mdx
@@ -1,5 +1,5 @@
 ---
-title: 'Before you start'
+title: 'Before You Start'
 originalFilePath: 'src/before_you_start.md'
 ---
 

diff --git a/product_docs/docs/postgres_distributed_for_kubernetes/1/certificates.mdx b/product_docs/docs/postgres_distributed_for_kubernetes/1/certificates.mdx
@@ -6,24 +6,243 @@ originalFilePath: 'src/certificates.md'
 EDB Postgres Distributed for Kubernetes was designed to natively support TLS certificates.
 To set up an PGD cluster, each PGD node requires:
 
--   A server certification authority (CA) certificate
--   A server TLS certificate signed by the server CA
--   A client CA certificate
--   A streaming replication client certificate generated by the client CA
+-   Server certificates configuration.
+-   Client certificates configuration.
 
 !!! Note
     You can find all the secrets used by each PGD node and the expiry dates in
     the cluster (PGD node) status.
 
-EDB Postgres Distributed for Kubernetes is very flexible when it comes to TLS certificates. It
-operates primarily in two modes:
+## Server certificates configuration
 
--  **Operator managed** &mdash; Certificates are internally
-    managed by the operator in a fully automated way and signed using a CA created
-    by EDB Postgres Distributed for Kubernetes.
--  **User provided** &mdash; Certificates are
-    generated outside the operator and imported in the cluster definition as
-    secrets. EDB Postgres Distributed for Kubernetes integrates itself with cert-manager.
+The server certificate configuration is handled in the `spec.connectivity.tls.serverCert`
+section of the PGDGroup custom resource. This configuration requires a server CA secret
+and a cert-manager template to generate the TLS certificates needed for the underlying
+Postgres instance to terminate TLS connections.
 
-For more information, see the
+The following assumptions must be met for this section to function correctly:
+
+1.  Cert-manager must be installed.
+2.  An issuer specified `spec.connectivity.tls.serverCert.certManager.issuerRef` is available
+    for the domain specified in `spec.connectivity.dns.domain` and any additional domains listed
+    in `spec.connectivity.tls.serverCert.certManager.spec.dnsNames`.
+3.  A server CA secret containing the public certificate of the CA used by the
+    issuer must be created.
+
+!!! Note
+    The server CA secret specified by `spec.connectivity.tls.clientCert.serverCA`
+    will be referenced as `serverCASecret` in the underlying CNP nodes.  The
+    public part, `ca.crt`, validates the server certificate and is included as `sslrootcert`
+    into client connection strings. The private part, `ca.key`, is used to automatically sign
+    the server SSL certificate, if a self-signed certificate is employed.
+
+!!! Note
+    The server TLS secret generated by PGD group will be specified as the value of `serverTLSSecret`
+    in the underlying CNP nodes. For more information, refer to [server certificates](/postgres_for_kubernetes/latest/certificates/#server-certificates-1).
+
+### DNS names
+
+The operator will add the following `altDnsNames` to the server TLS certificate:
+
+```
+${nodeName}${hostSuffix}.${domain}
+${groupName}${hostSuffix}.${domain}
+${proxyName}${hostSuffix}.${domain}
+${nodeName}${additionalHostSuffix}.${additionalDomain}
+${groupName}${additionalHostSuffix}.${additionalDomain}
+${proxyName}${additionalHostSuffix}.${additionalDomain}
+```
+
+Users are responsible for including any necessary names in
+`spec.connectivity.tls.serverCert.certManager.spec.dnsNames`, based on their underlying networking
+architecture (e.g. any load balancers to access the nodes).
+
+For example, consider a PGD Group configured as follows:
+
+```yaml
+apiVersion: pgd.k8s.enterprisedb.io/v1beta1
+kind: PGDGroup
+metadata:
+  name: region-a
+spec:
+  instances: 3
+  ...
+  connectivity:
+    dns:
+      # we need to configure the domain for the group so it could be resolved
+      domain: enterprisedb.network
+      additional:
+        - domain: alternate.network
+          hostSuffix: -dc1
+```
+
+All of the following Subject Alternative Names (SANs) will be added to the
+server TLS certificate:
+
+```
+region-a-1-node.domain.enterprisedb.network
+region-a-group.domain.enterprisedb.network
+region-a-proxy.domain.enterprisedb.network
+region-a-1-node-dc1.alternate.network
+region-a-group-dc1.alternate.network
+region-a-proxy-dc1.alternate.network
+```
+
+## Client certificates configuration
+
+The client certificates configuration is managed under the
+`spec.connectivity.tls.clientCert` section of the PGDGroup custom resource.
+This configuration requires a client CA secret and a client cert-manager template
+to generate the client streaming replication certificate for the `streaming_replica`
+Postgres user.
+
+The following assumptions must be met for this section to function properly:
+
+1.  Cert-manager must be installed.
+2.  An issuer specified in `spec.connectivity.tls.clientCert.certManager.issuerRef` is available;
+    this issuer will be used to sign a certificate with the common name `streaming_replica`.
+3.  A client CA secret must be present. It contains the public certificate of the CA used by the issuer.
+
+The operator will use the configuration under `spec.connectivity.tls.clientCert.certManager`
+to create a certificate request for the `streaming_replica` Postgres user.
+The resulting certificate will be used to secure communication between the nodes.
+
+!!! Note
+    The client CA secret specified by `spec.connectivity.tls.clientCert.clientCA`
+    will be used as the value of `clientCASecret` in the underlying CNP nodes. The
+    public part, `ca.crt`, will be provided as `ssl_ca_file` to all the instances,
+    allowing them to verify client certificates they have signed. The private part,
+    `ca.key`, is optional and can be used to sign client certificate generated by
+    the [kubectl cnp plugin](/postgres_for_kubernetes/latest/kubectl-plugin/).
+
+### Client pre-provisioned replication certificate
+
+Alternatively, you can specify a secret containing the pre-provisioned client certificate
+for the `streaming_replica` user using the
+`spec.connectivity.tls.clientCert.preProvisioned.streamingReplica.secretRef` option. In this
+case, the certificate lifecycle is managed entirely by a third party (manually or automatically),
+by simply updating the content of the secret.
+
+!!! Note
+    Regardless of how the client streaming replication certificate is provided, it will be
+    used as the value of `replicationTLSSecret` in the underlying CNP nodes. For more information,
+    refer to the section on [Client certificate](/postgres_for_kubernetes/latest/certificates/#client-certificate).
+
+## TLS mode
+
+You can configure the TLS mode, which determines how the server certificates are verified during
+communication between nodes, using `spec.connectivity.tls.mode`. Its default value is
+`verify-ca`. Note that the TLS mode cannot be changed once the PGD Group is set up. The
+`mode` accepts the following values,  as documented in [SSL Support](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS) in the PostgreSQL documentation:
+
+-   `verify-full`
+-   `verify-ca`
+-   `required`
+
+## Self-signed example
+
+This example demonstrates how to use cert-manager to setup a self-signed CA and
+generated required certificates.
+
+First, we need to generate the server and client CA certificates. We will create two self-signed issuers,
+`server-ca-issuer` and `client-ca-issuer`, in the target namespace.
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: selfsigned-issuer
+spec:
+  selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: server-ca-issuer
+spec:
+  ca:
+    secretName: server-ca-key-pair
+---
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: client-ca-issuer
+spec:
+  ca:
+    secretName: client-ca-key-pair
+```
+
+With the following Certificate object, we can generate the private key and a signed
+certificate from the issuer. The private key and signed certificate will be stored in the
+secrets named `server-ca-key-pair` and `client-ca-key-pair`.
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: server-ca
+spec:
+  isCA: true
+  commonName: my-selfsigned-server-ca
+  secretName: server-ca-key-pair
+  privateKey:
+    algorithm: ECDSA
+    size: 256
+  issuerRef:
+    name: selfsigned-issuer
+    kind: Issuer
+    group: cert-manager.io
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: client-ca
+spec:
+  isCA: true
+  commonName: my-selfsigned-client-ca
+  secretName: client-ca-key-pair
+  privateKey:
+    algorithm: ECDSA
+    size: 256
+  issuerRef:
+    name: selfsigned-issuer
+    kind: Issuer
+    group: cert-manager.io
+```
+
+We can now configure the PGD group. The `server-ca-key-pair` and `client-ca-key-pair`
+will be used as the server CA secret and client CA secret, respectively. The cert-manager template
+can be set up to reference the corresponding issuer to automatically generate the server TLS certificate
+and client replication certificate.
+
+```yaml
+apiVersion: pgd.k8s.enterprisedb.io/v1beta1
+kind: PGDGroup
+metadata:
+  name: region-a
+spec:
+  ...
+  connectivity:
+    tls:
+      mode: verify-ca
+      clientCert:
+        caCertSecret: client-ca-key-pair
+        certManager:
+          spec:
+            issuerRef:
+              name: client-ca-issuer
+              kind: Issuer
+              group: cert-manager.io
+      serverCert:
+        caCertSecret: server-ca-key-pair
+        certManager:
+          spec:
+            issuerRef:
+              name: server-ca-issuer
+              kind: Issuer
+              group: cert-manager.io
+
+```
+
+For more information about how certificate works, see the
 [EDB Postgres for Kubernetes documentation](/postgres_for_kubernetes/latest/certificates/).