diff --git a/_topic_map.yml b/_topic_map.yml index f0ca72cffc0d..fc1c48c80373 100644 --- a/_topic_map.yml +++ b/_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 diff --git a/modules/serverless-openshift-routes.adoc b/modules/serverless-openshift-routes.adoc new file mode 100644 index 000000000000..b192f615157a --- /dev/null +++ b/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: + annotations: + serving.knative.openshift.io/disableRoute: true +spec: + template: + spec: + containers: + - 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: <2> + namespace: knative-serving-ingress <3> +spec: + 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 `-.`. +<5> The certificates you want to use. Currently, only `edge` termination is supported. diff --git a/serverless/networking/serverless-configuring-routes.adoc b/serverless/networking/serverless-configuring-routes.adoc new file mode 100644 index 000000000000..e78b239af4c4 --- /dev/null +++ b/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] diff --git a/serverless/networking/serverless-domain-mapping.adoc b/serverless/networking/serverless-domain-mapping.adoc index b0c733029622..3a273e833a79 100644 --- a/serverless/networking/serverless-domain-mapping.adoc +++ b/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, `..example.com`. +Knative services are automatically assigned a default domain name based on your cluster configuration. For example, `..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.