You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Add documentation about custom TLS secrets, clarifying replication secret common name
* Bump streaming standby test secrets to have 10y expiration
Issue: [sc-14645]
Copy file name to clipboardExpand all lines: docs/content/tutorial/customize-cluster.md
+41-11Lines changed: 41 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -99,11 +99,18 @@ If you want to use the TLS infrastructure that PGO provides, you can skip the re
99
99
100
100
### How to Customize TLS
101
101
102
-
There are a few different TLS endpoints that can be customized for PGO, including those of the Postgres cluster and controlling how Postgres instances authenticate with each other. Let's look at how we can customize TLS.
102
+
There are a few different TLS endpoints that can be customized for PGO, including those of the Postgres cluster and controlling how Postgres instances authenticate with each other. Let's look at how we can customize TLS by defining
103
103
104
-
Your TLS certificate should have a Common Name (CN) setting that matches the primary Service name. This is the name of the cluster suffixed with `-primary`. For example, for our `hippo` cluster this would be `hippo-primary`.
104
+
* a `spec.customTLSSecret`, used to both identify the cluster and encrypt communications; and
105
+
* a `spec.customReplicationTLSSecret`, used for replication authentication.
105
106
106
-
To customize the TLS for a Postgres cluster, you will need to create a Secret in the Namespace of your Postgres cluster that contains the TLS key (`tls.key`), TLS certificate (`tls.crt`) and the CA certificate (`ca.crt`) to use. The Secret should contain the following values:
107
+
(For more information on the `spec.customTLSSecret` and `spec.customReplicationTLSSecret` fields, see the [`PostgresCluster CRD`]({{< relref "references/crd.md" >}}).)
108
+
109
+
To customize the TLS for a Postgres cluster, you will need to create two Secrets in the Namespace of your Postgres cluster. One of these Secrets will be the `customTLSSecret` and the other will be the `customReplicationTLSSecret`. Both secrets contain a TLS key (`tls.key`), TLS certificate (`tls.crt`) and CA certificate (`ca.crt`) to use.
110
+
111
+
Note: If `spec.customTLSSecret` is provided you **must** also provide `spec.customReplicationTLSSecret` and both must contain the same `ca.crt`.
112
+
113
+
The custom TLS and custom replication TLS Secrets should contain the following fields (though see below for a workaround if you cannot control the field names of the Secret's `data`):
107
114
108
115
```
109
116
data:
@@ -112,39 +119,62 @@ data:
112
119
tls.key: <value>
113
120
```
114
121
115
-
For example, if you have files named `ca.crt`, `hippo.key`, and `hippo.crt` stored on your local machine, you could run the following command:
122
+
For example, if you have files named `ca.crt`, `hippo.key`, and `hippo.crt` stored on your local machine, you could run the following command to create a Secret from those files:
You can specify the custom TLS Secret in the `spec.customTLSSecret.name` field in your `postgrescluster.postgres-operator.crunchydata.com` custom resource, e.g.:
131
+
After you create the Secrets, you can specify the custom TLS Secret in your `postgrescluster.postgres-operator.crunchydata.com` custom resource. For example, if you created a `hippo-cluster.tls` Secret and a `hippo-replication.tls` Secret, you would add them to your Postgres cluster:
132
+
133
+
```
134
+
spec:
135
+
customTLSSecret:
136
+
name: hippo-cluster.tls
137
+
customReplicationTLSSecret:
138
+
name: hippo-replication.tls
139
+
```
140
+
141
+
If you're unable to control the key-value pairs in the Secret, you can create a mapping to tell
142
+
the Postgres Operator what key holds the expected value. That would look similar to this:
125
143
126
144
```
127
145
spec:
128
146
customTLSSecret:
129
147
name: hippo.tls
148
+
items:
149
+
- key: <tls.crt key in the referenced hippo.tls Secret>
150
+
path: tls.crt
151
+
- key: <tls.key key in the referenced hippo.tls Secret>
152
+
path: tls.key
153
+
- key: <ca.crt key in the referenced hippo.tls Secret>
154
+
path: ca.crt
130
155
```
131
156
132
-
If you're unable to control the key-value pairs in the Secret, you can create a mapping that looks similar to this:
157
+
For instance, if the `hippo.tls` Secret had the `tls.crt` in a key named `hippo-tls.crt`, the
158
+
`tls.key` in a key named `hippo-tls.key`, and the `ca.crt` in a key named `hippo-ca.crt`,
159
+
then your mapping would look like:
133
160
134
161
```
135
162
spec:
136
163
customTLSSecret:
137
164
name: hippo.tls
138
165
items:
139
-
- key: <tls.crt key>
166
+
- key: hippo-tls.crt
140
167
path: tls.crt
141
-
- key: <tls.key key>
168
+
- key: hippo-tls.key
142
169
path: tls.key
143
-
- key: <ca.crt key>
170
+
- key: hippo-ca.crt
144
171
path: ca.crt
145
172
```
146
173
147
-
If `spec.customTLSSecret` is provided you **must** also provide `spec.customReplicationTLSSecret` and both must contain the same `ca.crt`.
174
+
Note: Although the custom TLS and custom replication TLS Secrets share the same `ca.crt`, they do not share the same `tls.crt`:
175
+
176
+
* Your `spec.customTLSSecret` TLS certificate should have a Common Name (CN) setting that matches the primary Service name. This is the name of the cluster suffixed with `-primary`. For example, for our `hippo` cluster this would be `hippo-primary`.
177
+
* Your `spec.customReplicationTLSSecret` TLS certificate should have a Common Name (CN) setting that matches `_crunchyrepl`, which is the preset replication user.
148
178
149
179
As with the other changes, you can roll out the TLS customizations with `kubectl apply`.
0 commit comments