Skip to content

Commit 91ed0bf

Browse files
josh-heyerjosh-heyer
authored
Merge pull request #6378 from EnterpriseDB/content/pg4k-pgd/v1.1.0
PG4K-PGD v1.1.0 import
2 parents 8de4357 + 6633487 commit 91ed0bf

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+2526
-613
lines changed

‎product_docs/docs/postgres_distributed_for_kubernetes/1/architecture.mdx

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: 'Architecture'
33
originalFilePath: 'src/architecture.md'
44
---
55

6-
Consider these main architectural aspects
6+
Consider these main architectural aspects
77
when deploying EDB Postgres Distributed in Kubernetes.
88

99
EDB Postgres Distributed for Kubernetes is a
@@ -13,7 +13,7 @@ running in private, public, hybrid, or multi-cloud environments.
1313

1414
## Relationship with EDB Postgres Distributed
1515

16-
[EDB Postgres Distributed (PGD)](https://www.enterprisedb.com/docs/pgd/latest/)
16+
[EDB Postgres Distributed (PGD)](/pgd/latest/)
1717
is a multi-master implementation of Postgres designed for high performance and
1818
availability.
1919
PGD generally requires deployment using
@@ -75,7 +75,7 @@ EDB Postgres Distributed for Kubernetes manages the following:
7575

7676
PGD groups assume full mesh connectivity of PGD nodes. Each node must be able to
7777
connect to every other node using the appropriate connection string (a
78-
`libpq`-style DSN). Write operations don't need to be sent to every node. PGD
78+
`libpq`-style DSN). Write operations don't need to be sent to every node. PGD
7979
takes care of replicating data after it's committed to one node.
8080

8181
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
126126
distribution. These are the *operands*.
127127
In addition, the operator images are kept in those same repositories.
128128

129-
See [EDB private image registries](identify_images/private_registries.md)
129+
See [EDB private image registries](private_edb_registries.md)
130130
for details on accessing the images.
131131

132132
### Kubernetes architecture
@@ -194,6 +194,6 @@ For more information, see ["Connectivity"](connectivity.md).
194194

195195
!!! Note Regions and availability zones
196196

197-
When creating Kubernetes clusters in different regions or availability zones for cross-regional replication,
198-
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
199-
[Submariner](https://submariner.io/) on every cluster.
197+
When creating Kubernetes clusters in different regions or availability zones for cross-regional replication,
198+
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
199+
[Submariner](https://submariner.io/) on every cluster.

‎product_docs/docs/postgres_distributed_for_kubernetes/1/before_you_start.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: 'Before you start'
2+
title: 'Before You Start'
33
originalFilePath: 'src/before_you_start.md'
44
---
55

‎product_docs/docs/postgres_distributed_for_kubernetes/1/certificates.mdx

Lines changed: 232 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,243 @@ originalFilePath: 'src/certificates.md'
66
EDB Postgres Distributed for Kubernetes was designed to natively support TLS certificates.
77
To set up an PGD cluster, each PGD node requires:
88

9-
- A server certification authority (CA) certificate
10-
- A server TLS certificate signed by the server CA
11-
- A client CA certificate
12-
- A streaming replication client certificate generated by the client CA
9+
- Server certificates configuration.
10+
- Client certificates configuration.
1311

1412
!!! Note
1513
You can find all the secrets used by each PGD node and the expiry dates in
1614
the cluster (PGD node) status.
1715

18-
EDB Postgres Distributed for Kubernetes is very flexible when it comes to TLS certificates. It
19-
operates primarily in two modes:
16+
## Server certificates configuration
2017

21-
- **Operator managed** — Certificates are internally
22-
managed by the operator in a fully automated way and signed using a CA created
23-
by EDB Postgres Distributed for Kubernetes.
24-
- **User provided** — Certificates are
25-
generated outside the operator and imported in the cluster definition as
26-
secrets. EDB Postgres Distributed for Kubernetes integrates itself with cert-manager.
18+
The server certificate configuration is handled in the `spec.connectivity.tls.serverCert`
19+
section of the PGDGroup custom resource. This configuration requires a server CA secret
20+
and a cert-manager template to generate the TLS certificates needed for the underlying
21+
Postgres instance to terminate TLS connections.
2722

28-
For more information, see the
23+
The following assumptions must be met for this section to function correctly:
24+
25+
1. Cert-manager must be installed.
26+
2. An issuer specified `spec.connectivity.tls.serverCert.certManager.issuerRef` is available
27+
for the domain specified in `spec.connectivity.dns.domain` and any additional domains listed
28+
in `spec.connectivity.tls.serverCert.certManager.spec.dnsNames`.
29+
3. A server CA secret containing the public certificate of the CA used by the
30+
issuer must be created.
31+
32+
!!! Note
33+
The server CA secret specified by `spec.connectivity.tls.clientCert.serverCA`
34+
will be referenced as `serverCASecret` in the underlying CNP nodes. The
35+
public part, `ca.crt`, validates the server certificate and is included as `sslrootcert`
36+
into client connection strings. The private part, `ca.key`, is used to automatically sign
37+
the server SSL certificate, if a self-signed certificate is employed.
38+
39+
!!! Note
40+
The server TLS secret generated by PGD group will be specified as the value of `serverTLSSecret`
41+
in the underlying CNP nodes. For more information, refer to [server certificates](/postgres_for_kubernetes/latest/certificates/#server-certificates-1).
42+
43+
### DNS names
44+
45+
The operator will add the following `altDnsNames` to the server TLS certificate:
46+
47+
```
48+
${nodeName}${hostSuffix}.${domain}
49+
${groupName}${hostSuffix}.${domain}
50+
${proxyName}${hostSuffix}.${domain}
51+
${nodeName}${additionalHostSuffix}.${additionalDomain}
52+
${groupName}${additionalHostSuffix}.${additionalDomain}
53+
${proxyName}${additionalHostSuffix}.${additionalDomain}
54+
```
55+
56+
Users are responsible for including any necessary names in
57+
`spec.connectivity.tls.serverCert.certManager.spec.dnsNames`, based on their underlying networking
58+
architecture (e.g. any load balancers to access the nodes).
59+
60+
For example, consider a PGD Group configured as follows:
61+
62+
```yaml
63+
apiVersion: pgd.k8s.enterprisedb.io/v1beta1
64+
kind: PGDGroup
65+
metadata:
66+
name: region-a
67+
spec:
68+
instances: 3
69+
...
70+
connectivity:
71+
dns:
72+
# we need to configure the domain for the group so it could be resolved
73+
domain: enterprisedb.network
74+
additional:
75+
- domain: alternate.network
76+
hostSuffix: -dc1
77+
```
78+
79+
All of the following Subject Alternative Names (SANs) will be added to the
80+
server TLS certificate:
81+
82+
```
83+
region-a-1-node.domain.enterprisedb.network
84+
region-a-group.domain.enterprisedb.network
85+
region-a-proxy.domain.enterprisedb.network
86+
region-a-1-node-dc1.alternate.network
87+
region-a-group-dc1.alternate.network
88+
region-a-proxy-dc1.alternate.network
89+
```
90+
91+
## Client certificates configuration
92+
93+
The client certificates configuration is managed under the
94+
`spec.connectivity.tls.clientCert` section of the PGDGroup custom resource.
95+
This configuration requires a client CA secret and a client cert-manager template
96+
to generate the client streaming replication certificate for the `streaming_replica`
97+
Postgres user.
98+
99+
The following assumptions must be met for this section to function properly:
100+
101+
1. Cert-manager must be installed.
102+
2. An issuer specified in `spec.connectivity.tls.clientCert.certManager.issuerRef` is available;
103+
this issuer will be used to sign a certificate with the common name `streaming_replica`.
104+
3. A client CA secret must be present. It contains the public certificate of the CA used by the issuer.
105+
106+
The operator will use the configuration under `spec.connectivity.tls.clientCert.certManager`
107+
to create a certificate request for the `streaming_replica` Postgres user.
108+
The resulting certificate will be used to secure communication between the nodes.
109+
110+
!!! Note
111+
The client CA secret specified by `spec.connectivity.tls.clientCert.clientCA`
112+
will be used as the value of `clientCASecret` in the underlying CNP nodes. The
113+
public part, `ca.crt`, will be provided as `ssl_ca_file` to all the instances,
114+
allowing them to verify client certificates they have signed. The private part,
115+
`ca.key`, is optional and can be used to sign client certificate generated by
116+
the [kubectl cnp plugin](/postgres_for_kubernetes/latest/kubectl-plugin/).
117+
118+
### Client pre-provisioned replication certificate
119+
120+
Alternatively, you can specify a secret containing the pre-provisioned client certificate
121+
for the `streaming_replica` user using the
122+
`spec.connectivity.tls.clientCert.preProvisioned.streamingReplica.secretRef` option. In this
123+
case, the certificate lifecycle is managed entirely by a third party (manually or automatically),
124+
by simply updating the content of the secret.
125+
126+
!!! Note
127+
Regardless of how the client streaming replication certificate is provided, it will be
128+
used as the value of `replicationTLSSecret` in the underlying CNP nodes. For more information,
129+
refer to the section on [Client certificate](/postgres_for_kubernetes/latest/certificates/#client-certificate).
130+
131+
## TLS mode
132+
133+
You can configure the TLS mode, which determines how the server certificates are verified during
134+
communication between nodes, using `spec.connectivity.tls.mode`. Its default value is
135+
`verify-ca`. Note that the TLS mode cannot be changed once the PGD Group is set up. The
136+
`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:
137+
138+
- `verify-full`
139+
- `verify-ca`
140+
- `required`
141+
142+
## Self-signed example
143+
144+
This example demonstrates how to use cert-manager to setup a self-signed CA and
145+
generated required certificates.
146+
147+
First, we need to generate the server and client CA certificates. We will create two self-signed issuers,
148+
`server-ca-issuer` and `client-ca-issuer`, in the target namespace.
149+
150+
```yaml
151+
apiVersion: cert-manager.io/v1
152+
kind: Issuer
153+
metadata:
154+
name: selfsigned-issuer
155+
spec:
156+
selfSigned: {}
157+
---
158+
apiVersion: cert-manager.io/v1
159+
kind: Issuer
160+
metadata:
161+
name: server-ca-issuer
162+
spec:
163+
ca:
164+
secretName: server-ca-key-pair
165+
---
166+
apiVersion: cert-manager.io/v1
167+
kind: Issuer
168+
metadata:
169+
name: client-ca-issuer
170+
spec:
171+
ca:
172+
secretName: client-ca-key-pair
173+
```
174+
175+
With the following Certificate object, we can generate the private key and a signed
176+
certificate from the issuer. The private key and signed certificate will be stored in the
177+
secrets named `server-ca-key-pair` and `client-ca-key-pair`.
178+
179+
```yaml
180+
apiVersion: cert-manager.io/v1
181+
kind: Certificate
182+
metadata:
183+
name: server-ca
184+
spec:
185+
isCA: true
186+
commonName: my-selfsigned-server-ca
187+
secretName: server-ca-key-pair
188+
privateKey:
189+
algorithm: ECDSA
190+
size: 256
191+
issuerRef:
192+
name: selfsigned-issuer
193+
kind: Issuer
194+
group: cert-manager.io
195+
---
196+
apiVersion: cert-manager.io/v1
197+
kind: Certificate
198+
metadata:
199+
name: client-ca
200+
spec:
201+
isCA: true
202+
commonName: my-selfsigned-client-ca
203+
secretName: client-ca-key-pair
204+
privateKey:
205+
algorithm: ECDSA
206+
size: 256
207+
issuerRef:
208+
name: selfsigned-issuer
209+
kind: Issuer
210+
group: cert-manager.io
211+
```
212+
213+
We can now configure the PGD group. The `server-ca-key-pair` and `client-ca-key-pair`
214+
will be used as the server CA secret and client CA secret, respectively. The cert-manager template
215+
can be set up to reference the corresponding issuer to automatically generate the server TLS certificate
216+
and client replication certificate.
217+
218+
```yaml
219+
apiVersion: pgd.k8s.enterprisedb.io/v1beta1
220+
kind: PGDGroup
221+
metadata:
222+
name: region-a
223+
spec:
224+
...
225+
connectivity:
226+
tls:
227+
mode: verify-ca
228+
clientCert:
229+
caCertSecret: client-ca-key-pair
230+
certManager:
231+
spec:
232+
issuerRef:
233+
name: client-ca-issuer
234+
kind: Issuer
235+
group: cert-manager.io
236+
serverCert:
237+
caCertSecret: server-ca-key-pair
238+
certManager:
239+
spec:
240+
issuerRef:
241+
name: server-ca-issuer
242+
kind: Issuer
243+
group: cert-manager.io
244+
245+
```
246+
247+
For more information about how certificate works, see the
29248
[EDB Postgres for Kubernetes documentation](/postgres_for_kubernetes/latest/certificates/).

0 commit comments

Comments
 (0)