Merge pull request #77492 from openshift-cherrypick-robot/cherry-pick-76392-to-enterprise-4.16

[enterprise-4.16] OSDOCS6774: Created new section to update support router to load secrets

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

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=<secret-name> \ <1> 
+--namespace=<current-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=<current-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: <secret-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 <route.yaml> <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.
+====

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].