diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 94a905defd..c403de8a6d 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1133,6 +1133,8 @@ Topics: File: cert-manager-operator-issuer-acme - Name: Configuring certificates with an issuer File: cert-manager-creating-certificate + - Name: Securing routes with the cert-manager Operator for Red Hat OpenShift + File: cert-manager-securing-routes - Name: Monitoring the cert-manager Operator for Red Hat OpenShift File: cert-manager-monitoring - Name: Configuring log levels for cert-manager and the cert-manager Operator for Red Hat OpenShift diff --git a/modules/cert-manager-configuring-routes.adoc b/modules/cert-manager-configuring-routes.adoc new file mode 100644 index 0000000000..8da6d9dce5 --- /dev/null +++ b/modules/cert-manager-configuring-routes.adoc @@ -0,0 +1,150 @@ +// Module included in the following assemblies: +// +// * security/cert_manager_operator/cert-manager-creating-certificate.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cert-manager-configuring-routes_{context}"] += Configuring certificates to secure routes in your cluster + +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. + +.Prerequisites + +* You have installed the {cert-manager-operator} 1.14.0 or later. +* You have enabled the `RouteExternalCertificate` feature gate. +* You have the `create` and `update` permissions on the `routes/custom-host` sub-resource. +* You have a `Service` resource that you want to expose. + +.Procedure + +. 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. ++ +[source, terminal] +---- +$ oc create route edge \ # <1> + --service= \ # <2> + --hostname= \ # <3> + --namespace= # <4> +---- +<1> Specify your route's name. +<2> Specify the service you want to expose. +<3> Specify the hostname of your route. +<4> Specify the namespace where your route is located. + +. Create an `Issuer` to configure the HTTP-01 solver by running the following command. For other ACME issuer types, see "Configuring ACME an issuer". ++ +.Example `Issuer.yaml` file ++ +[source, yaml] +---- +$ oc create -f - << EOF +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: letsencrypt-acme + namespace: # <1> +spec: + acme: + server: https://acme-v02.api.letsencrypt.org/directory + privateKeySecretRef: + name: letsencrypt-acme-account-key + solvers: + - http01: + ingress: + ingressClassName: openshift-default +EOF +---- +<1> Specify the namespace where the `Issuer` is located. It should be the same as your route's namespace. + +. 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. ++ +[source, yaml] +---- +$ oc create -f - << EOF +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: example-route-cert + namespace: # <1> +spec: + commonName: # <2> + dnsNames: + - # <3> + usages: + - server auth + issuerRef: + kind: Issuer + name: letsencrypt-acme + secretName: # <4> +EOF +---- +<1> Specify the `namespace` where the `Certificate` resource is located. It should be the same as your route's namespace. +<2> Specify the certificate's common name using the hostname of the route. +<3> Add the hostname of your route to the certificate's DNS names. +<4> Specify the name of the secret that contains the certificate. + +. Create a `Role` to provide the router service account permissions to read the referenced secret by using the following command: ++ +[source, terminal] +---- +$ oc create role secret-reader \ + --verb=get,list,watch \ + --resource=secrets \ + --resource-name= \ # <1> + --namespace= # <2> +---- +<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. +<2> Specify the namespace where both your secret and route are located. + +. Create a `RoleBinding` resource to bind the router service account with the newly created `Role` resource by using the following command: ++ +[source, terminal] +---- +$ oc create rolebinding secret-reader-binding \ + --role=secret-reader \ + --serviceaccount=openshift-ingress:router \ + --namespace= # <1> +---- +<1> Specify the namespace where both your secret and route are located. + +. 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: ++ +[source, terminal] +---- +$ oc patch route \ # <1> + -n \ # <2> + --type=merge \ + -p '{"spec":{"tls":{"externalCertificate":{"name":""}}}}' # <3> +---- +<1> Specify the route name. +<2> Specify the namespace where both your secret and route are located. +<3> Specify the name of the secret that contains the certificate. + +.Verification + +* Verify that the certificate is created and ready to use by running the following command: ++ +[source, terminal] +---- +$ oc get certificate -n <1> +$ oc get secret -n <1> +---- +<1> Specify the namespace where both your secret and route reside. + +* 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`. ++ +[source, terminal] +---- +$ curl -IsS https:// <1> +---- +<1> Specify the hostname of your route. + +* Verify the server certificate's `subject`, `subjectAltName` and `issuer` are all as expected from the curl verbose outputs by running the following command: ++ +[source, terminal] +---- +$ curl -v https:// <1> +---- +<1> Specify the hostname of your route. ++ +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. \ No newline at end of file diff --git a/security/cert_manager_operator/cert-manager-securing-routes.adoc b/security/cert_manager_operator/cert-manager-securing-routes.adoc new file mode 100644 index 0000000000..df42e9566c --- /dev/null +++ b/security/cert_manager_operator/cert-manager-securing-routes.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cert-manager-securing-routes"] += Securing routes with the {cert-manager-operator} +include::_attributes/common-attributes.adoc[] +:context: cert-manager-securing-routes + +toc::[] + +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. + +:FeatureName: Securing routes with the {cert-manager-operator} +include::snippets/technology-preview.adoc[] + +include::modules/cert-manager-configuring-routes.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* xref:../../networking/routes/secured-routes.adoc#nw-ingress-route-secret-load-external-cert_secured-routes[Creating a route with externally managed certificate] + +* xref:../../security/cert_manager_operator/cert-manager-operator-issuer-acme.adoc#cert-manager-operator-issuer-acme[Configuring an ACME issuer] \ No newline at end of file