From 4f5a75b266857b6257a082832df1c843b80acaee Mon Sep 17 00:00:00 2001 From: subhtk Date: Thu, 23 May 2024 11:48:34 +0530 Subject: [PATCH] Created new section for route secret load for external certificate --- ...-integrating-route-secret-certificate.adoc | 6 ++ ...gress-route-secret-load-external-cert.adoc | 82 +++++++++++++++++++ networking/routes/secured-routes.adoc | 7 ++ 3 files changed, 95 insertions(+) create mode 100644 modules/nw-ingress-integrating-route-secret-certificate.adoc create mode 100644 modules/nw-ingress-route-secret-load-external-cert.adoc diff --git a/modules/nw-ingress-integrating-route-secret-certificate.adoc b/modules/nw-ingress-integrating-route-secret-certificate.adoc new file mode 100644 index 0000000000..4ac39bf62f --- /dev/null +++ b/modules/nw-ingress-integrating-route-secret-certificate.adoc @@ -0,0 +1,6 @@ +// +// * ingress/routes.adoc + +:_mod-docs-content-type: PROCEDURE +[id="nw-ingress-integrating-route-secret-certificate_{context}"] += Securing route with external certificates in TLS secrets diff --git a/modules/nw-ingress-route-secret-load-external-cert.adoc b/modules/nw-ingress-route-secret-load-external-cert.adoc new file mode 100644 index 0000000000..2b39444ff2 --- /dev/null +++ b/modules/nw-ingress-route-secret-load-external-cert.adoc @@ -0,0 +1,82 @@ +// Module included in the following assemblies: +// +// * networking/routes/secured-routes.adoc + +:_mod-docs-content-type: PROCEDURE +[id="nw-ingress-route-secret-load-external-cert_{context}"] += Creating a route with externally managed certificate + +:FeatureName: Securing route with external certificates in TLS secrets +include::snippets/technology-preview.adoc[] + +You can configure {product-title} routes with third-party certificate management solutions by using the `.spec.tls.externalCertificate` field of the route API. You can reference externally managed TLS certificates via secrets, eliminating the need for manual certificate management. Using the externally managed certificate reduces errors ensuring a smoother rollout of certificate updates, enabling the OpenShift router to serve renewed certificates promptly. + +[NOTE] +==== +This feature applies to both edge routes and re-encrypt routes. +==== + +.Prerequisites + +* You must enable the `RouteExternalCertificate` feature gate. +* You must have the `create` and `update` permissions on the `routes/custom-host`. +* You must have a secret containing a valid certificate/key pair in PEM-encoded format of type `kubernetes.io/tls`, which includes both `tls.key` and `tls.crt` keys. +* You must place the referenced secret in the same namespace as the route you want to secure. + +.Procedure + +. Create a `role` in the same namespace as the secret to allow the router service account read access by running the following command: ++ +[source,terminal] +---- +$ oc create role secret-reader --verb=get,list,watch --resource=secrets --resource-name= \ <1> +--namespace= <2> +---- +<1> Specify the actual name of your secret. +<2> Specify the namespace where both your secret and route reside. + +. Create a `rolebinding` in the same namespace as the secret and bind the router service account to the newly created role by running 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 reside. + +. Create a YAML file that defines the `route` and specifies the secret containing your certificate using the following example. ++ +.YAML definition of the secure route +[source,yaml] +---- +apiVersion: route.openshift.io/v1 +kind: Route +metadata: + name: myedge + namespace: test +spec: + host: myedge-test.apps.example.com + tls: + externalCertificate: + name: <1> + termination: edge + [...] +[...] +---- +<1> Specify the actual name of your secret. + +. Create a `route` resource by running the following command: ++ +[source,terminal] +---- +$ oc apply -f <1> +---- +<1> Specify the generated YAML filename. + +If the secret exists and has a certificate/key pair, the router will serve the generated certificate if all prerequisites are met. + +[NOTE] +==== +If `.spec.tls.externalCertificate` is not provided, the router will use default generated certificates. + +You cannot provide the `.spec.tls.certificate` field or the `.spec.tls.key` field when using the `.spec.tls.externalCertificate` field. +==== diff --git a/networking/routes/secured-routes.adoc b/networking/routes/secured-routes.adoc index 5cd7bef361..7bd896457f 100644 --- a/networking/routes/secured-routes.adoc +++ b/networking/routes/secured-routes.adoc @@ -25,3 +25,10 @@ include::modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate include::modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc[leveloffset=+1] include::modules/nw-ingress-creating-a-passthrough-route.adoc[leveloffset=+1] + +include::modules/nw-ingress-route-secret-load-external-cert.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* For troubleshooting routes with externally managed certificates, check the {product-title} router pod logs for errors, see xref:../../support/troubleshooting/investigating-pod-issues.adoc[Investigating pod issues]. \ No newline at end of file