SRVKS-719: Updating service mesh + serverless docs

Author: abrennan89

_topic_map.yml

@@ -2998,6 +2998,9 @@ Topics:
     File: upgrading-serverless
   - Name: Removing OpenShift Serverless
     File: removing-openshift-serverless
+    # Ingress options
+  - Name: Integrating Service Mesh with OpenShift Serverless
+    File: serverless-ossm-setup
     # Eventing
   - Name: Creating Knative Eventing components in the Administrator perspective
     File: serverless-cluster-admin-eventing
@@ -3036,6 +3039,17 @@ Topics:
   # Tracing
   - Name: Tracing requests using Jaeger
     File: serverless-tracing
+    # JWT using kourier
+  - Name: Configuring JSON Web Token authentication for Knative services
+    File: serverless-ossm-with-kourier-jwt
+    # Custom domains
+  - Name: Configuring a custom domain for a Knative service
+    File: serverless-custom-domains
+  - Name: Configuring TLS for a custom domain
+    File: serverless-ossm-tls-with-kourier
+    # Routes
+  - Name: Configuring routes for Knative services
+    File: serverless-configuring-routes
 #
 # Knative Eventing
 - Name: Knative Eventing
@@ -3112,24 +3126,6 @@ Topics:
     File: serverless-functions-eventing
   - Name: Functions development reference guide
     File: serverless-functions-reference-guide
-#
-# Networking
-- Name: Networking
-  Dir: networking
-  Topics:
-  - 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
-    File: serverless-ossm-jwt
-  - Name: Using custom domains for Knative services with Service Mesh
-    File: serverless-ossm-custom-domains
-  - Name: Configuring TLS for a custom domain using Service Mesh
-    File: serverless-ossm-tls
-#
 # Integrations
 - Name: Integrations
   Dir: integrations

modules/serverless-config-replicas.adoc

@@ -3,13 +3,12 @@
 
 High availability (HA) functionality is available by default on {ServerlessProductName} for the `autoscaler-hpa`, `controller`, `activator`, `kourier-control`, and `kourier-gateway` controllers. These components are configured with two replicas by default.
 
-You modify the number of replicas that are created per controller by changing the configuration of `KnativeServing.spec.highAvailability` in the KnativeServing custom resource definition.
-// This field also specifies the minimum number of _activators_ if you are using the horizontal pod autoscaler (HPA). For more information about HPA, see
+You can modify the number of replicas that are created per controller by changing the configuration of the `high-availability` spec in the `KnativeServing` custom resource definition (CRD).
 
 .Prerequisites
 
-* An {product-title} account with cluster administrator access.
-* Installed the {ServerlessOperatorName} and Knative Serving.
+* You have access to an {product-title} cluster with cluster administrator permissions.
+* The {ServerlessOperatorName} and Knative Serving are installed on your cluster.
 
 .Procedure
 
@@ -27,7 +26,7 @@ image::serving-tab-created.png[Knative Serving tab]
 +
 image::serving-YAML-HA.png[Knative Serving YAML]
 +
-. Edit the custom resource definition YAML:
+. Modify the number of replicas in the `KnativeServing` CRD:
 +
 .Example YAML
 [source,yaml]

modules/serverless-create-domain-mapping.adoc

@@ -10,7 +10,7 @@ To map a custom domain name to a custom resource (CR), you must create a `Domain
 +
 [NOTE]
 ====
-Your custom domain must point to the DNS of the {product-title} cluster.
+Your custom domain must point to the IP address of the {product-title} cluster.
 ====
 
 .Procedure

modules/serverless-openshift-routes.adoc

@@ -1,6 +1,3 @@
-// Module included in the following assemblies:
-// * serverless/networking/serverless-configuring-routes.adoc
-
 [id="serverless-openshift-routes_{context}"]
 = Configuring {product-title} routes for Knative services
 
@@ -10,11 +7,17 @@ If you want to configure a Knative service to use your TLS certificate on {produ
 
 * The {ServerlessOperatorName} and Knative Serving component must be installed on your {product-title} cluster.
 
+[NOTE]
+====
+You must modify the replaceable values in the example commands for the following procedure.
+====
+
 .Procedure
 
 . Create a Knative service that includes the `serving.knative.openshift.io/disableRoute=true` annotation:
+.. Optional. Create a Knative service resource:
 +
-.Example YAML
+.Example resource
 [source,yaml]
 ----
 apiVersion: serving.knative.dev/v1
@@ -29,11 +32,18 @@ spec:
       containers:
       - image: <image>
 ----
+.. Apply the `Service` resource:
++
+[source,terminal]
+----
+$ oc apply -f <filename>
+----
+.. Optional. Create a Knative service by using the `kn service create` command:
 +
 .Example `kn` command
 [source,terminal]
 ----
-$ kn service create hello-example \
+$ kn service create <service_name> \
   --image=gcr.io/knative-samples/helloworld-go \
   --annotation serving.knative.openshift.io/disableRoute=true
 ----
@@ -43,17 +53,20 @@ $ kn service create hello-example \
 .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
+$ $ 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:
+You will 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:
+. Create a `Route` resource in the `knative-serving-ingress` namespace:
 +
 [source,yaml]
 ----
@@ -94,3 +107,9 @@ spec:
 <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.
+. Apply the `Route` resource:
++
+[source,terminal]
+----
+$ oc apply -f <filename>
+----

…rvice-mesh-enable-sidecar-injection.adoc …able-sidecar-injection-with-kourier.adocmodules/serverless-service-mesh-enable-sidecar-injection.adoc renamed to modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc modules/serverless-service-mesh-enable-sidecar-injection.adoc renamed to modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc

@@ -1,43 +1,38 @@
-// Module included in the following assemblies:
-// * serverless/networking/serverless-ossm.adoc
-// * serverless/networking/serverless-ossm-jwt.adoc
-
-[id="serverless-enable-sidecar_{context}"]
+[id="serverless-ossm-enable-sidecar-injection-with-kourier_{context}"]
 = Enabling sidecar injection for a Knative service
 
 You can add the `sidecar.istio.io/inject="true"` annotation to a Knative service to enable sidecar injection for that service.
 
 [IMPORTANT]
 ====
-Adding sidecar injection to pods in system namespaces such as `knative-serving` and `knative-serving-ingress` is not supported.
+Adding sidecar injection to pods in system namespaces, such as `knative-serving` and `knative-serving-ingress`, is not supported when Kourier is enabled.
+
+If you require sidecar injection for pods in these namespaces, see the {ServerlessProductName} documentation on _Integrating {ProductShortName} with {ServerlessProductName} natively_.
 ====
+// Add an xref here once it's enabled for modules
 
 .Procedure
 
-. Add the `sidecar.istio.io/inject="true"` annotation to the `Service` resource YAML file:
+. Add the `sidecar.istio.io/inject="true"` annotation to your `Service` resource:
 +
-.Example service YAML
+.Example service
 [source,yaml]
 ----
 apiVersion: serving.knative.dev/v1
 kind: Service
 metadata:
-  name: hello-example-1
+  name: <service_name>
 spec:
   template:
     metadata:
       annotations:
         sidecar.istio.io/inject: "true" <1>
         sidecar.istio.io/rewriteAppHTTPProbers: "true" <2>
-    spec:
-      containers:
-      - image: docker.io/openshift/hello-openshift
-        name: container
+...
 ----
 <1> Add the `sidecar.istio.io/inject="true"` annotation.
 <2> Optional: Add the `sidecar.istio.io/rewriteAppHTTPProbers="true"` annotation if you have enabled JSON Web Token (JWT) authentication.
-
-. Apply the `Service` resource YAML file:
+. Apply your `Service` resource YAML file:
 +
 [source,terminal]
 ----

modules/serverless-ossm-setup-with-kourier.adoc

@@ -0,0 +1,70 @@
+[id="serverless-ossm-setup-with-kourier_{context}"]
+= Integrating {ProductShortName} with {ServerlessProductName} when Kourier is enabled
+
+.Prerequisites
+
+* You have installed the {ServerlessOperatorName} on your {product-title} cluster.
+* You have installed {ProductName}. {ServerlessProductName} with {ProductShortName} and Kourier is supported for use with both {ProductName} versions 1.x and 2.x.
+* You have installed Knative Serving.
+
+.Procedure
+
+. Add the namespaces that you would like to integrate with {ProductShortName} to the `ServiceMeshMemberRoll` object as members:
++
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshMemberRoll
+metadata:
+  name: default
+  namespace: istio-system
+spec:
+  members:
+    - <namespace> <1>
+----
+<1> A list of namespaces to be integrated with {ProductShortName}.
+. Apply the `ServiceMeshMemberRoll` resource:
++
+[source,terminal]
+----
+$ oc apply -f <filename>
+----
+. Create a network policy that permits traffic flow from Knative system pods to Knative services:
+.. Add the `serving.knative.openshift.io/system-namespace=true` label to the `knative-serving` namespace:
++
+[source,terminal]
+----
+$ oc label namespace knative-serving serving.knative.openshift.io/system-namespace=true
+----
+.. Add the `serving.knative.openshift.io/system-namespace=true` label to the `knative-serving-ingress` namespace:
++
+[source,terminal]
+----
+$ oc label namespace knative-serving-ingress serving.knative.openshift.io/system-namespace=true
+----
+.. For each namespace that you want to integrate with {ProductShortName}, create a `NetworkPolicy` resource:
++
+[source,yaml]
+----
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: allow-from-serving-system-namespace
+  namespace: <namespace> <1>
+spec:
+  ingress:
+  - from:
+    - namespaceSelector:
+        matchLabels:
+          serving.knative.openshift.io/system-namespace: "true"
+  podSelector: {}
+  policyTypes:
+  - Ingress
+----
+<1> Add the namespace that you want to integrate with {ProductShortName}.
+.. Apply the `NetworkPolicy` resource:
++
+[source,terminal]
+----
+$ oc apply -f <filename>
+----