PR for SRVCOM-3999: Add a new “Integrating Service Mesh 3.x with OpenShift Serverless" section in the serverless docs

_topic_maps/_topic_map.yml

@@ -511,6 +511,8 @@ Topics:
     File: serverless-ossm-setup
   - Name: Using Service Mesh 2.x to isolate network traffic with OpenShift Serverless
     File: serverless-ossm-traffic-isolation
+  - Name: Integrating Service Mesh 3.x with OpenShift Serverless
+    File: serverless-integrating-ossm-3-x-setup
 - Name: Integrating OpenShift Serverless with the cost management service
   File: serverless-cost-management-integration
 - Name: Integrating OpenShift Serverless with OpenShift Pipelines

integrations/serverless-integrating-service-mesh/serverless-integrating-ossm-3-x-setup.adoc

@@ -0,0 +1,52 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="serverless-integrating-ossm-3-x-setup"]
+= Integrating Service Mesh 3.x with OpenShift Serverless
+include::_attributes/common-attributes.adoc[]
+:context: serverless-integrating-ossm-3-x-setup
+
+toc::[]
+
+[role="_abstract"]
+The {ServerlessOperatorName} provides Kourier as the default ingress for Knative. However, you can use {SMProductShortName} with {ServerlessProductName} whether Kourier is enabled or not. Integrating with Kourier disabled allows you to configure additional networking and routing options that the Kourier ingress does not support, such as mTLS functionality.
+
+Note the following assumptions and limitations:
+
+* All Knative internal components, as well as Knative Services, are part of the {SMProductShortName} and have sidecars injection enabled. This means that strict mTLS is enforced within the whole mesh. All requests to Knative Services require an mTLS connection, with the client having to send its certificate, except calls coming from OpenShift Routing.
+
+* {ServerlessProductName} with {SMProductShortName} integration can only target *one* service mesh. Multiple meshes can be present in the cluster, but {ServerlessProductName} is only available on one of them.
+
+[id="prerequisites_serverless-integrating-ossm-3-x-setup"]
+== Prerequisites
+
+* You have access to an {product-title} account with cluster administrator access.
+
+* You have installed the OpenShift CLI (`oc`).
+
+* You have installed the {ServerlessProductShortName} Operator.
+
+* You have installed the {SMProductName} 3.x Operator.
+
+* The examples in the following procedures use the domain `example.com`. The example certificate for this domain is used as a certificate authority (CA) that signs the subdomain certificate.
++
+To complete and verify these procedures in your deployment, you need either a certificate signed by a widely trusted public CA or a CA provided by your organization. Example commands must be adjusted according to your domain, subdomain, and CA.
+
+* You must configure the wildcard certificate to match the domain of your {ocp-product-title} cluster. For example, if your {ocp-product-title} console address is `https://console-openshift-console.apps.openshift.example.com`, you must configure the wildcard certificate so that the domain is `*.apps.openshift.example.com`. For more information about configuring wildcard certificates, see the following topic about _Creating a certificate to encrypt incoming external traffic_.
+
+* If you want to use any domain name, including those which are not subdomains of the default {ocp-product-title} cluster domain, you must set up domain mapping for those domains. For more information, see the {ServerlessProductName} documentation about xref:../../knative-serving/config-custom-domains/create-domain-mapping.adoc#serverless-create-domain-mapping_create-domain-mapping[Creating a custom domain mapping].
+
+include::modules/serverless-ossm-external-certs.adoc[leveloffset=+1]
+
+[id="configuring-verifying-ossm-3-x-integration-with-serverless"]
+== Configuring and verifying {SMProductShortName} 3.x integration with {ServerlessProductName}
+
+You can integrate {SMProductShortName} 3.x with {ServerlessProductName} to enable advanced traffic management, security, and observability for your serverless applications. This section provides the steps to verify prerequisites, install and configure both components, and confirm that the integration is functioning as expected.
+
+include::modules/serverless-ossm-verifying-installation-prerequisites.adoc[leveloffset=+2]
+
+include::modules/serverless-ossm-installing-and-configuring-openshift-service-mesh-3-x.adoc[leveloffset=+2]
+
+include::modules/serverless-ossm-installing-and-configuring-openshift-serverless.adoc[leveloffset=+2]
+
+include::modules/serverless-ossm-verifying-the-ossm-3-x-integration.adoc[leveloffset=+2]
+
+include::modules/serverless-ossm-disabling-network-policies.adoc[leveloffset=+1]

modules/serverless-ossm-disabling-network-policies.adoc

@@ -2,10 +2,11 @@
 //
 // * /serverless/integrations/serverless-ossm-setup.adoc
 
-:_content-type: PROCEDURE
+:_mod-docs-content-type: PROCEDURE
 [id="serverless-ossm-disabling-network-policies_{context}"]
 = Disabling the default network policies 
 
+[role="_abstract"]
 The {ServerlessOperatorName} generates the network policies by default. To disable the default network policy generation, you can add the `serverless.openshift.io/disable-istio-net-policies-generation` annotation in the `KnativeEventing` and `KnativeServing` custom resources (CRs).
 
 .Prerequisites

modules/serverless-ossm-installing-and-configuring-openshift-serverless.adoc

@@ -1,7 +1,8 @@
-:_content-type: PROCEDURE
+:_mod-docs-content-type: PROCEDURE
 [id="serverless-ossm-installing-and-configuring-openshift-serverless_{context}"]
 = Installing and configuring {ServerlessProductShortName}
 
+[role="_abstract"]
 After installing {SMProductShortName}, you need to install {ServerlessProductShortName} with a specific configuration.
 
 .Procedure
@@ -16,6 +17,8 @@ kind: KnativeServing
 metadata:
   name: knative-serving
   namespace: knative-serving
+  annotations:
+    serverless.openshift.io/disable-istio-net-policies-generation: "true"
 spec:
   ingress:
     istio:
@@ -57,31 +60,42 @@ kind: KnativeEventing
 metadata:
   name: knative-eventing
   namespace: knative-eventing
+  annotations:
+    serverless.openshift.io/disable-istio-net-policies-generation: "true"
 spec:
   config:
     features:
-      istio: enabled <1>
-  workloads: <2>
-  - name: pingsource-mt-adapter
-    labels:
-      "sidecar.istio.io/inject": "true"
-    annotations:
-      "sidecar.istio.io/rewriteAppHTTPProbers": "true"
-  - name: imc-dispatcher
-    labels:
-      "sidecar.istio.io/inject": "true"
-    annotations:
-      "sidecar.istio.io/rewriteAppHTTPProbers": "true"
-  - name: mt-broker-ingress
-    labels:
-      "sidecar.istio.io/inject": "true"
-    annotations:
-      "sidecar.istio.io/rewriteAppHTTPProbers": "true"
-  - name: mt-broker-filter
-    labels:
-      "sidecar.istio.io/inject": "true"
-    annotations:
-      "sidecar.istio.io/rewriteAppHTTPProbers": "true"
+      istio: enabled  # <1>
+  workloads:  # <2>
+    - name: pingsource-mt-adapter
+      labels:
+        sidecar.istio.io/inject: "true"
+      annotations:
+        sidecar.istio.io/rewriteAppHTTPProbers: "true"
+
+    - name: imc-dispatcher
+      labels:
+        sidecar.istio.io/inject: "true"
+      annotations:
+        sidecar.istio.io/rewriteAppHTTPProbers: "true"
+
+    - name: mt-broker-ingress
+      labels:
+        sidecar.istio.io/inject: "true"
+      annotations:
+        sidecar.istio.io/rewriteAppHTTPProbers: "true"
+
+    - name: mt-broker-filter
+      labels:
+        sidecar.istio.io/inject: "true"
+      annotations:
+        sidecar.istio.io/rewriteAppHTTPProbers: "true"
+
+    - name: job-sink
+      labels:
+        sidecar.istio.io/inject: "true"
+      annotations:
+        sidecar.istio.io/rewriteAppHTTPProbers: "true"
 ----
 <1> Enable Eventing Istio controller to create a `DestinationRule` for each `InMemoryChannel` or `KafkaChannel` service.
 <2> Enable sidecar injection for Knative Eventing pods.

modules/serverless-ossm-installing-and-configuring-openshift-service-mesh-3-x.adoc

@@ -0,0 +1,236 @@
+:_mod-docs-content-type: PROCEDURE
+[id="serverless-ossm-installing-and-configuring-openshift-service-mesh-3-x_{context}"]
+= Installing and configuring {SMProductShortName} 3.x
+
+[role="_abstract"]
+You can integrate {SMProductShortName} 3.x with {ServerlessProductShortName} by installing and configuring the required Istio components, gateways, and Knative Serving resources. Once these resources are configured, you can deploy the Knative Serving instance with Istio enabled to ensure that your serverless workloads run within the {SMProductShortName} environment. 
+
+.Procedure
+
+. Create an `Istio` resource in the `istio-system` namespace with the following configuration:
++
+[source,yaml]
+----
+apiVersion: sailoperator.io/v1
+kind: Istio
+metadata:
+  name: default
+spec:
+  values:
+    meshConfig:
+      defaultConfig:
+        terminationDrainDuration: 35s
+  updateStrategy:
+    inactiveRevisionDeletionGracePeriodSeconds: 30
+    type: InPlace
+  namespace: istio-system
+  version: v1.26-latest
+----
+
+. Apply the resource by running the following commands:
++
+[source,terminal]
+----
+$ oc new-project istio-system
+----
++
+[source,terminal]
+----
+$ oc apply -f istio.yaml
+----
+
+. Create an `IstioCNI` resource in the `istio-cni` namespace with the following configuration:
++
+[source,yaml]
+----
+apiVersion: sailoperator.io/v1
+kind: IstioCNI
+metadata:
+  name: default
+spec:
+  namespace: istio-cni
+  version: v1.26-latest
+----
+
+. Apply the resource by running the following commands:
++
+[source,terminal]
+----
+$ oc new-project istio-cni
+----
++
+[source,terminal]
+----
+$ oc apply -f istio-cni.yaml
+----
+
+. Create a file named `gateway-deploy.yaml` with the following configuration:
++
+[source,yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: knative-istio-ingressgateway
+  namespace: knative-serving-ingress
+spec:
+  selector:
+    matchLabels:
+      knative: ingressgateway
+  template:
+    metadata:
+      annotations:
+        inject.istio.io/templates: gateway <1>
+      labels:
+        knative: ingressgateway <2>
+        sidecar.istio.io/inject: "true" <3>
+    spec:
+      containers:
+        - name: istio-proxy
+          image: auto <4>
+
+---
+# Set up roles to allow reading credentials for TLS
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: istio-ingressgateway-sds
+  namespace: knative-serving-ingress
+rules:
+  - apiGroups: [""]
+    resources: ["secrets"]
+    verbs: ["get", "watch", "list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: istio-ingressgateway-sds
+  namespace: knative-serving-ingress
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: istio-ingressgateway-sds
+subjects:
+  - kind: ServiceAccount
+    name: default
+----
++
+<1> Select the gateway injection template rather than the default sidecar template.
+<2> Set a unique label for the gateway. This is required to ensure Gateways can select this workload.
+<3> Enable gateway injection.
+<4> The image will automatically update each time the pod starts.
+
+. Apply the resource by running the following commands:
++
+[source,terminal]
+----
+$ oc apply -f gateway-deploy.yaml
+----
+
+. Create gateway resources for the Knative Serving component by creating a file named `serving-gateways.yaml` with the following configuration:
++
+[source,yaml]
+----
+###########################################################
+# cluster external
+###########################################################
+apiVersion: v1
+kind: Service
+metadata:
+  name: knative-istio-ingressgateway
+  namespace: knative-serving-ingress
+spec:
+  type: ClusterIP
+  selector:
+    knative: ingressgateway
+  ports:
+    - name: http2
+      port: 80
+      targetPort: 8080
+    - name: https
+      port: 443
+      targetPort: 8443
+---
+apiVersion: networking.istio.io/v1beta1
+kind: Gateway
+metadata:
+  name: knative-ingress-gateway
+  namespace: knative-serving
+spec:
+  selector:
+    knative: ingressgateway
+  servers:
+    - hosts:
+        - '*'
+      port:
+        name: https
+        number: 443
+        protocol: HTTPS
+      tls:
+        credentialName: wildcard-certs
+        mode: SIMPLE
+---
+###########################################################
+# cluster local
+###########################################################
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    experimental.istio.io/disable-gateway-port-translation: "true"
+  name: knative-local-gateway
+  namespace: knative-serving-ingress
+spec:
+  ports:
+    - name: http2
+      port: 80
+      protocol: TCP
+      targetPort: 8081
+  selector:
+    knative: ingressgateway
+  type: ClusterIP
+---
+apiVersion: networking.istio.io/v1beta1
+kind: Gateway
+metadata:
+  name: knative-local-gateway
+  namespace: knative-serving
+spec:
+  selector:
+    knative: ingressgateway
+  servers:
+    - hosts:
+        - '*'
+      port:
+        name: http
+        number: 8081
+        protocol: HTTP
+----
+
+. Apply the resource by running the following commands:
++
+[source,terminal]
+----
+$ oc apply -f serving-gateways.yaml
+----
+
+. Create a `PeerAuthentication` resource in the `istio-system` namespace to enforce mTLS across the mesh with the following configuration:
++
+[source,yaml]
+----
+apiVersion: security.istio.io/v1
+kind: PeerAuthentication
+metadata:
+  name: mesh-mtls
+  namespace: istio-system
+spec:
+  mtls:
+    mode: STRICT
+----
+
+. Apply the resource by running the following commands:
++
+[source,terminal]
+----
+$ oc apply -f peerauth.yaml
+----