Skip to content

Commit 2df8693

Browse files
dfitzmaudfitzmau
authored
Merge pull request #102604 from dfitzmau/OSDOCS-17251
OSDOCS-17251: Added rollout statements to cert-manager-certificate-in…
2 parents 3fa5566 + 3de039e commit 2df8693

File tree

2 files changed

+75
-34
lines changed

2 files changed

+75
-34
lines changed

‎modules/cert-manager-certificate-ingress.adoc‎

Lines changed: 50 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,20 @@
66
[id="cert-manager-certificate-ingress_{context}"]
77
= Creating certificates for the Ingress Controller
88

9+
[role="_abstract"]
10+
You can create a certificate for the Ingress Controller and then replace bootstrapped default self-signed certificates with cert-manager-managed external certificates.
11+
12+
[NOTE]
13+
====
14+
Before using the procedure, ensure you understand the following Ingress Controller behaviors:
15+
16+
* When certificates are renewed or rotated by using the cert-manager Operator, only the contents of the secret, such as the certificate and key, are updated. The secret name remains unchanged. Kubelet automatically propagates these updates to the mounted volume, allowing the router to detect the file changes and hot-reload the new certificate and key. As a result, no rolling update of the router deployment is triggered or required.
17+
18+
* The secret name is referenced in the Ingress Controller configuration. If you want to replace the default ingress certificate or use different secret name in Ingress Controller configuration, you must patch or edit the configuration to apply the change. This operation triggers a rolling update for router pods where new router pods load the new cert/key pair.
19+
20+
For more information, see this link:https://access.redhat.com/solutions/4542531[Red{nbsp}Hat Knowledgebase Solution].
21+
====
22+
923
.Prerequisites
1024

1125
* You have access to the cluster with `cluster-admin` privileges.
@@ -16,38 +30,41 @@
1630
. Create an issuer. For more information, see "Configuring an issuer" in the "Additional resources" section.
1731

1832
. Create a certificate:
19-
33+
+
2034
.. Create a YAML file, for example, `certificate.yaml`, that defines the `Certificate` object:
2135
+
2236
.Example `certificate.yaml` file
23-
+
24-
[source, yaml]
37+
[source,yaml]
2538
----
2639
apiVersion: cert-manager.io/v1
2740
kind: Certificate
2841
metadata:
29-
name: <tls_cert> #<1>
42+
name: <tls_cert>
3043
namespace: openshift-ingress
3144
spec:
3245
isCA: false
33-
commonName: "apps.<cluster_base_domain>" #<2>
34-
secretName: <secret_name> #<3>
46+
commonName: "apps.<cluster_base_domain>"
47+
secretName: <secret_name>
3548
dnsNames:
36-
- "apps.<cluster_base_domain>" #<4>
37-
- "*.apps.<cluster_base_domain>" #<4>
49+
- "apps.<cluster_base_domain>"
50+
- "\*.apps.<cluster_base_domain>"
3851
issuerRef:
39-
name: <issuer_name> #<5>
52+
name: <issuer_name>
4053
kind: Issuer
4154
----
42-
<1> Provide a name for the certificate.
43-
<2> Specify the common name (CN).
44-
<3> Specify the name of the secret to create that contains the certificate.
45-
<4> Specify the DNS name of the ingress.
46-
<5> Specify the name of the issuer.
55+
+
56+
where:
57+
+
58+
`<tls_cert>`:: Specifies the name for the certificate.
59+
`<cluster_base_domain>`:: Specifies the common name (CN).
60+
`<secret_name>`:: Specifies the name of the secret to create that contains the certificate.
61+
`<cluster_base_domain>`:: Specifies the DNS name of the ingress.
62+
`<issuer_name>`:: Specifies the name of the issuer.
4763

64+
+
4865
.. Create the `Certificate` object by running the following command:
4966
+
50-
[source, terminal]
67+
[source,terminal]
5168
----
5269
$ oc create -f certificate.yaml
5370
----
@@ -56,11 +73,25 @@ $ oc create -f certificate.yaml
5673

5774
.Verification
5875

59-
* Verify that the certificate is created and ready to use by running the following command:
76+
. Verify that the certificate is created and ready to use by running the following command:
77+
+
78+
[source,terminal]
79+
----
80+
$ oc get certificate -n openshift-ingress
81+
----
82+
83+
. Verify the definition and content of the secret object by running the following command:
84+
+
85+
[source,terminal]
86+
----
87+
$ oc get secret <secretName> -n openshift-ingress
88+
----
89+
90+
. Verify that the default TLS certificate has the correct configuration details for the Ingress Controller by running the following command:
6091
+
61-
[source, terminal]
92+
[source,terminal]
6293
----
63-
$ oc get certificate -w -n openshift-ingress
94+
$ oc get ingresscontroller default -n openshift-ingress-operator -o yaml | grep -A2 defaultCertificate
6495
----
6596
+
66-
Once certificate is in `Ready` status, Ingress Controller on your cluster can start using the generated certificate secret.
97+
After the certificate is in `Ready` status, the Ingress Controller on your cluster can start using the generated certificate secret.

‎modules/customize-certificates-replace-default-router.adoc‎

Lines changed: 25 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,15 @@
88

99
You can replace the default ingress certificate for all applications under the `.apps` subdomain. After you replace the certificate, all applications, including the web console and CLI, have encryption provided by the specified certificate.
1010

11+
[NOTE]
12+
====
13+
Before using the procedure, ensure you understand the following Ingress Controller behaviors:
14+
15+
* When certificates are renewed or rotated by using external certificate management tools, only the contents of the secret, such as the certificate and key, are updated. The secret name remains unchanged. Kubelet automatically propagates these updates to the mounted volume, allowing the router to detect the file changes and hot-reload the new certificate and key. As a result, no rolling update of the router deployment is triggered or required.
16+
17+
* For secret renewal or rotation, the cert-manager Operator changes the secret content, such as a cert/key pair, but does not change the secret name. This happens because kubelet automatically propagates changes to the secret in the volume mount. The router pod detects the file change and then hot reloads the new cert/key pair. Updating the secret content does not trigger rolling update.
18+
====
19+
1120
.Prerequisites
1221

1322
* You must have a wildcard certificate for the fully qualified `.apps` subdomain and its corresponding private key. Each should be in a separate PEM format file.
@@ -24,10 +33,13 @@ You can replace the default ingress certificate for all applications under the `
2433
[source,terminal]
2534
----
2635
$ oc create configmap custom-ca \
27-
--from-file=ca-bundle.crt=</path/to/example-ca.crt> \//<1>
36+
--from-file=ca-bundle.crt=</path/to/example-ca.crt> \
2837
-n openshift-config
2938
----
30-
<1> `</path/to/example-ca.crt>` is the path to the root CA certificate file on your local file system. For example, `/etc/pki/ca-trust/source/anchors`.
39+
+
40+
where
41+
+
42+
`</path/to/example-ca.crt>`:: The path to the root CA certificate file on your local file system. For example, `/etc/pki/ca-trust/source/anchors`.
3143

3244
. Update the cluster-wide proxy configuration with the newly created config map:
3345
+
@@ -49,28 +61,26 @@ If you change any other parameter in the `openshift-config-user-ca-bundle.crt` f
4961
+
5062
[source,terminal]
5163
----
52-
$ oc create secret tls <secret> \//<1>
53-
--cert=</path/to/cert.crt> \//<2>
54-
--key=</path/to/cert.key> \//<3>
64+
$ oc create secret tls <secret> \
65+
--cert=</path/to/cert.crt> \
66+
--key=</path/to/cert.key> \
5567
-n openshift-ingress
5668
----
57-
<1> `<secret>` is the name of the secret that will contain the certificate chain and private key.
58-
<2> `</path/to/cert.crt>` is the path to the certificate chain on your local file system.
59-
<3> `</path/to/cert.key>` is the path to the private key associated with this certificate.
69+
+
70+
where:
71+
+
72+
`<secret>`:: Specifies the name of the secret that will contain the certificate chain and private key.
73+
`</path/to/cert.crt>`:: Specifies the path to the certificate chain on your local file system.
74+
`</path/to/cert.key>`:: Specifies the path to the private key associated with this certificate.
6075

6176
. Update the Ingress Controller configuration with the newly created secret:
6277
+
6378
[source,terminal]
6479
----
6580
$ oc patch ingresscontroller.operator default \
6681
--type=merge -p \
67-
'{"spec":{"defaultCertificate": {"name": "<secret>"}}}' \//<1>
82+
'{"spec":{"defaultCertificate": {"name": "<secret>"}}}' \
6883
-n openshift-ingress-operator
6984
----
70-
<1> Replace `<secret>` with the name used for the secret in the previous step.
7185
+
72-
[IMPORTANT]
73-
====
74-
To trigger the Ingress Operator to perform a rolling update, you must update the name of the secret.
75-
Because the kubelet automatically propagates changes to the secret in the volume mount, updating the secret contents does not trigger a rolling update. For more information, see this link:https://access.redhat.com/solutions/4542531[Red{nbsp}Hat Knowledgebase Solution].
76-
====
86+
* `<secret>`:: Specifies the name used for the secret. Replace `<secret>` with the name used for the secret.

0 commit comments

Comments
 (0)