Skip to content

Commit 88669b6

Browse files
adellapeadellape
authored
Merge pull request #78500 from subhtk/cm-354
OSDOCS 11250: Added securing routes with externally managed certificate section in cert-manager
2 parents 1cc1f6d + 645805f commit 88669b6

File tree

3 files changed

+174
-0
lines changed

3 files changed

+174
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1134,6 +1134,8 @@ Topics:
11341134
File: cert-manager-operator-issuer-acme
11351135
- Name: Configuring certificates with an issuer
11361136
File: cert-manager-creating-certificate
1137+
- Name: Securing routes with the cert-manager Operator for Red Hat OpenShift
1138+
File: cert-manager-securing-routes
11371139
- Name: Monitoring the cert-manager Operator for Red Hat OpenShift
11381140
File: cert-manager-monitoring
11391141
- Name: Configuring log levels for cert-manager and the cert-manager Operator for Red Hat OpenShift

‎modules/cert-manager-configuring-routes.adoc

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-creating-certificate.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="cert-manager-configuring-routes_{context}"]
7+
= Configuring certificates to secure routes in your cluster
8+
9+
The following steps demonstrate the process of utilizing the {cert-manager-operator} with the _Let's Encrypt_ ACME HTTP-01 challenge type to secure the route resources in your {product-title} cluster.
10+
11+
.Prerequisites
12+
13+
* You have installed the {cert-manager-operator} 1.14.0 or later.
14+
* You have enabled the `RouteExternalCertificate` feature gate.
15+
* You have the `create` and `update` permissions on the `routes/custom-host` sub-resource.
16+
* You have a `Service` resource that you want to expose.
17+
18+
.Procedure
19+
20+
. Create a `Route` resource for your `Service` resource using edge TLS termination and a custom hostname by running the following command. The hostname will be used while creating a `Certificate` resource in the following steps.
21+
+
22+
[source, terminal]
23+
----
24+
$ oc create route edge <route_name> \ # <1>
25+
--service=<service_name> \ # <2>
26+
--hostname=<hostname> \ # <3>
27+
--namespace=<namespace> # <4>
28+
----
29+
<1> Specify your route's name.
30+
<2> Specify the service you want to expose.
31+
<3> Specify the hostname of your route.
32+
<4> Specify the namespace where your route is located.
33+
34+
. Create an `Issuer` to configure the HTTP-01 solver by running the following command. For other ACME issuer types, see "Configuring ACME an issuer".
35+
+
36+
.Example `Issuer.yaml` file
37+
+
38+
[source, yaml]
39+
----
40+
$ oc create -f - << EOF
41+
apiVersion: cert-manager.io/v1
42+
kind: Issuer
43+
metadata:
44+
name: letsencrypt-acme
45+
namespace: <namespace> # <1>
46+
spec:
47+
acme:
48+
server: https://acme-v02.api.letsencrypt.org/directory
49+
privateKeySecretRef:
50+
name: letsencrypt-acme-account-key
51+
solvers:
52+
- http01:
53+
ingress:
54+
ingressClassName: openshift-default
55+
EOF
56+
----
57+
<1> Specify the namespace where the `Issuer` is located. It should be the same as your route's namespace.
58+
59+
. Create a `Certificate` object for the route by running the following command. The `secretName` specifies the TLS secret that is going to be issued and managed by cert-manager and will also be referenced in your route in the following steps.
60+
+
61+
[source, yaml]
62+
----
63+
$ oc create -f - << EOF
64+
apiVersion: cert-manager.io/v1
65+
kind: Certificate
66+
metadata:
67+
name: example-route-cert
68+
namespace: <namespace> # <1>
69+
spec:
70+
commonName: <hostname> # <2>
71+
dnsNames:
72+
- <hostname> # <3>
73+
usages:
74+
- server auth
75+
issuerRef:
76+
kind: Issuer
77+
name: letsencrypt-acme
78+
secretName: <secret_name> # <4>
79+
EOF
80+
----
81+
<1> Specify the `namespace` where the `Certificate` resource is located. It should be the same as your route's namespace.
82+
<2> Specify the certificate's common name using the hostname of the route.
83+
<3> Add the hostname of your route to the certificate's DNS names.
84+
<4> Specify the name of the secret that contains the certificate.
85+
86+
. Create a `Role` to provide the router service account permissions to read the referenced secret by using the following command:
87+
+
88+
[source, terminal]
89+
----
90+
$ oc create role secret-reader \
91+
--verb=get,list,watch \
92+
--resource=secrets \
93+
--resource-name=<secret_name> \ # <1>
94+
--namespace=<namespace> # <2>
95+
----
96+
<1> Specify the name of the secret that you want to grant access to. It should be consistent with your `secretName` specified in the `Certificate` resource.
97+
<2> Specify the namespace where both your secret and route are located.
98+
99+
. Create a `RoleBinding` resource to bind the router service account with the newly created `Role` resource by using the following command:
100+
+
101+
[source, terminal]
102+
----
103+
$ oc create rolebinding secret-reader-binding \
104+
--role=secret-reader \
105+
--serviceaccount=openshift-ingress:router \
106+
--namespace=<namespace> # <1>
107+
----
108+
<1> Specify the namespace where both your secret and route are located.
109+
110+
. Update your route's `.spec.tls.externalCertificate` field to reference the previously created secret and use the certificate issued by cert-manager by using the following command:
111+
+
112+
[source, terminal]
113+
----
114+
$ oc patch route <route_name> \ # <1>
115+
-n <namespace> \ # <2>
116+
--type=merge \
117+
-p '{"spec":{"tls":{"externalCertificate":{"name":"<secret_name>"}}}}' # <3>
118+
----
119+
<1> Specify the route name.
120+
<2> Specify the namespace where both your secret and route are located.
121+
<3> Specify the name of the secret that contains the certificate.
122+
123+
.Verification
124+
125+
* Verify that the certificate is created and ready to use by running the following command:
126+
+
127+
[source, terminal]
128+
----
129+
$ oc get certificate -n <namespace> <1>
130+
$ oc get secret -n <namespace> <1>
131+
----
132+
<1> Specify the namespace where both your secret and route reside.
133+
134+
* Verify that the router is using the referenced external certificate by running the following command. The command should return with the status code `200 OK`.
135+
+
136+
[source, terminal]
137+
----
138+
$ curl -IsS https://<hostname> <1>
139+
----
140+
<1> Specify the hostname of your route.
141+
142+
* Verify the server certificate's `subject`, `subjectAltName` and `issuer` are all as expected from the curl verbose outputs by running the following command:
143+
+
144+
[source, terminal]
145+
----
146+
$ curl -v https://<hostname> <1>
147+
----
148+
<1> Specify the hostname of your route.
149+
+
150+
The route is now successfully secured by the certificate from the referenced secret issued by cert-manager. cert-manager will automatically manage the certificate's lifecycle.

‎security/cert_manager_operator/cert-manager-securing-routes.adoc

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="cert-manager-securing-routes"]
3+
= Securing routes with the {cert-manager-operator}
4+
include::_attributes/common-attributes.adoc[]
5+
:context: cert-manager-securing-routes
6+
7+
toc::[]
8+
9+
In the {product-title}, the route API is extended to provide a configurable option to reference TLS certificates via secrets. With the xref:../../networking/routes/secured-routes.adoc#nw-ingress-route-secret-load-external-cert_secured-routes[Creating a route with externally managed certificate] Technology Preview feature enabled, you can minimize errors from manual intervention, streamline the certificate management process, and enable the {product-title} router to promptly serve the referenced certificate.
10+
11+
:FeatureName: Securing routes with the {cert-manager-operator}
12+
include::snippets/technology-preview.adoc[]
13+
14+
include::modules/cert-manager-configuring-routes.adoc[leveloffset=+1]
15+
16+
[role="_additional-resources"]
17+
[id="additional-resources_{context}"]
18+
== Additional resources
19+
20+
* xref:../../networking/routes/secured-routes.adoc#nw-ingress-route-secret-load-external-cert_secured-routes[Creating a route with externally managed certificate]
21+
22+
* xref:../../security/cert_manager_operator/cert-manager-operator-issuer-acme.adoc#cert-manager-operator-issuer-acme[Configuring an ACME issuer]

0 commit comments

Comments
 (0)