[srvls] [SRVKS-693] Route docs for serverless

_topic_map.yml

@@ -2871,8 +2871,10 @@ Topics:
 - Name: Networking
   Dir: networking
   Topics:
-  - Name: Mapping a custom domain name to a service
+  - Name: Mapping a custom domain name to a Knative service
     File: serverless-domain-mapping
+  - Name: Configuring routes for Knative services
+    File: serverless-configuring-routes
   - Name: Using Service Mesh with OpenShift Serverless
     File: serverless-ossm
   - Name: Using JSON Web Token authentication with Service Mesh and OpenShift Serverless

modules/serverless-openshift-routes.adoc

@@ -0,0 +1,96 @@
+// Module included in the following assemblies:
+// * serverless/networking/serverless-configuring-routes.adoc
+
+[id="serverless-openshift-routes_{context}"]
+= Configuring {product-title} routes for Knative services
+
+If you want to configure a Knative service to use your TLS certificate on {product-title}, you must disable the automatic creation of a route for the service by the {ServerlessOperatorName}, and instead manually create a `Route` resource for the service.
+
+.Prerequisites
+
+* The {ServerlessOperatorName} and Knative Serving component must be installed on your {product-title} cluster.
+
+.Procedure
+
+. Create a Knative service that includes the `serving.knative.openshift.io/disableRoute=true` annotation:
++
+.Example YAML
+[source,yaml]
+----
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: <service_name>
+  annotations:
+    serving.knative.openshift.io/disableRoute: true
+spec:
+  template:
+    spec:
+      containers:
+      - image: <image>
+----
++
+.Example `kn` command
+[source,terminal]
+----
+$ kn service create hello-example \
+  --image=gcr.io/knative-samples/helloworld-go \
+  --annotation serving.knative.openshift.io/disableRoute=true
+----
+
+. Verify that no {product-title} route has been created for the service:
++
+.Example command
+[source,terminal]
+----
+$ oc get routes.route.openshift.io -l serving.knative.openshift.io/ingressName=$KSERVICE_NAME -l serving.knative.openshift.io/ingressNamespace=$KSERVICE_NAMESPACE -n knative-serving-ingress
+----
++
+You should see the following output:
++
+[source,terminal]
+----
+No resources found in knative-serving-ingress namespace.
+----
+
+. Create a `Route` object in the `knative-serving-ingress` namespace by copying the following sample YAML and modifying the replaceable values:
++
+[source,yaml]
+----
+apiVersion: route.openshift.io/v1
+kind: Route
+metadata:
+  annotations:
+    haproxy.router.openshift.io/timeout: 600s <1>
+  name: <route_name> <2>
+  namespace: knative-serving-ingress <3>
+spec:
+  host: <service_host> <4>
+  port:
+    targetPort: http2
+  to:
+    kind: Service
+    name: kourier
+    weight: 100
+  tls:
+    insecureEdgeTerminationPolicy: Allow
+    termination: edge <5>
+    key: |-
+      -----BEGIN PRIVATE KEY-----
+      [...]
+      -----END PRIVATE KEY-----
+    certificate: |-
+      -----BEGIN CERTIFICATE-----
+      [...]
+      -----END CERTIFICATE-----
+    caCertificate: |-
+      -----BEGIN CERTIFICATE-----
+      [...]
+      -----END CERTIFICATE----
+  wildcardPolicy: None
+----
+<1> The timeout value for the {product-title} route. You must set the same value as the `max-revision-timeout-seconds` setting (`600s` by default).
+<2> The name of the {product-title} route.
+<3> The namespace for the {product-title} route. This must be `knative-serving-ingress`.
+<4> The hostname for external access. You can set this to `<service_name>-<service_namespace>.<domain>`.
+<5> The certificates you want to use. Currently, only `edge` termination is supported.

serverless/networking/serverless-configuring-routes.adoc

@@ -0,0 +1,15 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-configuring-routes"]
+= Configuring routes for Knative services
+:context: serverless-configuring-routes
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+Knative leverages {product-title} TLS termination to provide routing for Knative services. When a Knative service is created, a {product-title} route is automatically created for the service. This route is managed by the {ServerlessOperatorName}. The {product-title} route exposes the Knative service through the same domain as the {product-title} cluster.
+
+You can disable Operator control of {product-title} routing so that you can configure a Knative route to directly use your TLS certificates instead.
+
+Knative routes can also be used alongside the {product-title} route to provide additional fine-grained routing capabilities, such as traffic splitting.
+
+include::modules/serverless-openshift-routes.adoc[leveloffset=+1]

serverless/networking/serverless-domain-mapping.adoc

@@ -1,12 +1,12 @@
 include::modules/serverless-document-attributes.adoc[]
 [id="serverless-domain-mapping"]
-= Mapping a custom domain name to a service
+= Mapping a custom domain name to a Knative service
 :context: serverless-domain-mapping
 include::modules/common-attributes.adoc[]
 
 toc::[]
 
-Knative Services are automatically assigned a default domain name based on your cluster configuration. For example, `<service_name>.<namespace>.example.com`.
+Knative services are automatically assigned a default domain name based on your cluster configuration. For example, `<service_name>.<namespace>.example.com`.
 You can map a custom domain name that you own to a Knative service by creating a `DomainMapping` custom resource (CR) for the service.
 You can also create multiple CRs to map multiple domains and subdomains to a single service.