[serverless-docs-1.32] [SRVKS-1023] Add conceptual docs on the Kourier and Istio ingresses

_topic_maps/_topic_map.yml

@@ -136,6 +136,8 @@ Topics:
     File: restrictive-network-policies
 - Name: Debugging Serverless applications
   File: debugging-serverless-applications
+- Name: Kourier and Istio ingresses
+  File: kourier-and-istio-ingresses
 - Name: Traffic splitting
   Dir: traffic-splitting
   Topics:

install/installing-knative-serving.adoc

@@ -18,6 +18,12 @@ If you want to xref:../observability/tracing/serverless-tracing.adoc#serverless-
 include::modules/serverless-install-serving-web-console.adoc[leveloffset=+1]
 include::modules/serverless-install-serving-yaml.adoc[leveloffset=+1]
 
+[id="additional-resources_installing-knative-serving"]
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../knative-serving/kourier-and-istio-ingresses.adoc#kourier-and-istio-ingresses[Kourier and Istio ingresses]
+
 [id="next-steps_installing-knative-serving"]
 == Next steps
 

integrations/serverless-ossm-setup.adoc

@@ -46,6 +46,7 @@ Using {ServerlessProductShortName} 1.31 with {SMProductShortName} is only suppor
 [role="_additional-resources"]
 == Additional resources
 * link:https://access.redhat.com/articles/4912821[Red Hat OpenShift Serverless Supported Configurations]
+* xref:../knative-serving/kourier-and-istio-ingresses.adoc#kourier-and-istio-ingresses[Kourier and Istio ingresses]
 
 include::modules/serverless-ossm-external-certs.adoc[leveloffset=+1]
 

knative-serving/kourier-and-istio-ingresses.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="kourier-and-istio-ingresses"]
+= Kourier and Istio ingresses
+:context: kourier-and-istio-ingresses
+
+toc::[]
+
+{ServerlessProductName} supports the following two ingress solutions:
+
+* Kourier
+* Istio using {SMProductName}
+
+The default is Kourier.
+
+include::modules/serverless-kourier-and-istio-ingresses-overview.adoc[leveloffset=+1]

modules/serverless-kourier-and-istio-ingresses-overview.adoc

@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//
+// * knative-serving/kourier-and-istio-ingresses.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="serverless-kourier-and-istio-ingresses-solutions_{context}"]
+= Kourier and Istio ingress solutions
+
+[id="serverless-ingresses-kourier-overview_{context}"]
+== Kourier
+
+Kourier is the default ingress solution for {ServerlessProductName}. It has the following properties:
+
+* It is based on envoy proxy.
+* It is simple and lightweight.
+* It provides the basic routing functionality that {ServerlessProductShortName} needs to provide its set of features.
+* It supports basic observability and metrics.
+* It supports basic TLS termination of Knative Service routing.
+* It provides only limited configuration and extension options.
+
+[id="serverless-ingresses-istio-overview_{context}"]
+== Istio using OpenShift Service Mesh
+
+Using Istio as the ingress solution for {ServerlessProductName} enables an additional feature set that is based on what {SMProductName} offers:
+
+* Native mTLS between all connections
+* {ServerlessProductShortName} components are part of a service mesh
+* Additional observability and metrics
+* Authorization and authentication support
+* Custom rules and configuration, as supported by {SMProductName}
+
+However, the additional features come with a higher overhead and resource consumption. For details, see the {SMProductName} documentation.
+
+See the "Integrating Service Mesh with OpenShift Serverless" section of {ServerlessProductShortName} documentation for Istio requirements and installation instructions.
+
+[id="serverless-ingresses-traffic-configuration-and-routing_{context}"]
+== Traffic configuration and routing
+
+Regardless of whether you use Kourier or Istio, the traffic for a Knative Service is configured in the `knative-serving` namespace by the `net-kourier-controller` or the `net-istio-controller` respectively.
+
+The controller reads the `KnativeService` and its child custom resources to configure the ingress solution. Both ingress solutions provide an ingress gateway pod that becomes part of the traffic path. Both ingress solutions are based on Envoy. By default, {ServerlessProductShortName} has two routes for each `KnativeService` object:
+
+* A *cluster-external route* that is forwarded by the OpenShift router, for example `myapp-namespace.example.com`.
+* A *cluster-local route* containing the cluster domain, for example `myapp.namespace.svc.cluster.local`. This domain can and should be used to call Knative services from Knative or other user workloads.
+
+The ingress gateway can forward requests either in the serve mode or the proxy mode:
+
+* In the serve mode, requests go directly to the Queue-Proxy sidecar container of the Knative service.
+* In the proxy mode, requests first go through the Activator component in the `knative-serving` namespace.
+
+The choice of mode depends on the configuration of Knative, the Knative service, and the current traffic. For example, if a Knative Service is scaled to zero, requests are sent to the Activator component, which acts as a buffer until a new Knative service pod is started.