openshift · jab-rh · Dec 12, 2023 · Nov 28, 2023
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -170,6 +170,8 @@ Topics:
     File: kourier-gateway-service-type
   - Name: Using HTTP2 and gRPC
     File: using-http2-gRPC
+  - Name: Using Serving with OpenShift ingress sharding
+    File: using-serving-with-ingress-sharding
 - Name: Configuring access to Knative services
   Dir: config-access
   Topics:

diff --git a/knative-serving/external-ingress-routing/using-serving-with-ingress-sharding.adoc b/knative-serving/external-ingress-routing/using-serving-with-ingress-sharding.adoc
@@ -0,0 +1,27 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="using-serving-with-ingress-sharding_{context}"]
+= Using Serving with OpenShift ingress sharding
+:context: using-serving-with-ingress-sharding
+
+toc::[]  
+
+You can use Knative Serving with OpenShift ingress sharding to split ingress traffic based on domains. This allows you to manage and route network traffic to different parts of a cluster more efficiently.
+
+[NOTE]
+====
+Even with OpenShift ingress sharding in place, {ServerlessProductName} traffic is still routed through a single Knative Ingress Gateway and the activator component in the `knative-serving` project.
+
+For more information about isolating the network traffic, see xref:../../integrations/serverless-ossm-traffic-isolation.adoc#serverless-ossm-traffic-isolation[Using Service Mesh to isolate network traffic with OpenShift Serverless].
+====
+
+.Prerequisites
+
+* You have installed the {ServerlessOperatorName} and Knative Serving.
+* You have cluster administrator permissions on {ocp-product-title}, or you have cluster or dedicated administrator permissions on {rosa-product-title} or {dedicated-product-title}.
+
+
+include::modules/configuring-openshift-ingress-shards.adoc[leveloffset=+1]
+include::modules/configuring-custom-domains-in-knativeserving-CR.adoc[leveloffset=+1]
+include::modules/targeting-a-specific-ingress-shard-in-the-knative-service.adoc[leveloffset=+1]
+include::modules/verifying-serving-with-openshift-ingress-sharding-configuration.adoc[leveloffset=+1]
diff --git a/modules/configuring-custom-domains-in-knativeserving-CR.adoc b/modules/configuring-custom-domains-in-knativeserving-CR.adoc
@@ -0,0 +1,25 @@
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-custom-domains-in-knativeserving-CR_{context}"]
+= Configuring custom domains in the KnativeServing CR
+
+After configuring OpenShift ingress shards, you must configure Knative Serving to match them.
+
+.Procedure
+
+* In the `KnativeServing` CR, configure Serving to use the same domains and labels as your ingress shards by adding the `spec.config.domain` field:
++
+.Example `KnativeServing` CR
+[source,yaml]
+----
+spec:
+  config:
+    domain: # <1>
+      dev.serverless.cluster.example.com: |
+        selector:
+          router: dev
+      prod.serverless.cluster.example.com: |
+        selector:
+          router: prod
+  # ...
+----
+<1> These values need to match the values in the ingress shard configuration.
diff --git a/modules/configuring-openshift-ingress-shards.adoc b/modules/configuring-openshift-ingress-shards.adoc
@@ -0,0 +1,43 @@
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-openshift-ingress-shards_{context}"]
+= Configuring OpenShift ingress shards
+
+Before configuring Knative Serving, you must configure OpenShift ingress shards.
+
+.Procedure
+
+* Use a label selector in the `IngressController` CR to configure {ServerlessProductName} to match specific ingress shards with different domains:
++
+.Example `IngressController` CR
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name: ingress-dev # <1>
+  namespace: openshift-ingress-operator
+spec:
+  routeSelector:
+    matchLabels:
+      router: dev # <2>
+  domain: "dev.serverless.cluster.example.com" # <3>
+  # ...
+---
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name: ingress-prod # <4>
+  namespace: openshift-ingress-operator
+spec:
+  routeSelector:
+    matchLabels:
+      router: prod # <5>
+  domain: "prod.serverless.cluster.example.com" # <6>
+  # ...
+----
+<1> Name of the first ingress shard.
+<2> A label selector to match the `ingress-dev` shard.
+<3> A custom domain for the `ingress-dev` shard.
+<4> Name of the second ingress shard.
+<5> A label selector to match the `ingress-prod` shard.
+<6> A custom domain for the `ingress-prod` shard.
diff --git a/modules/targeting-a-specific-ingress-shard-in-the-knative-service.adoc b/modules/targeting-a-specific-ingress-shard-in-the-knative-service.adoc
@@ -0,0 +1,39 @@
+:_mod-docs-content-type: PROCEDURE
+[id="targeting-a-specific-ingress-shard-in-the-knative-service_{context}"]
+= Targeting a specific ingress shard in the Knative Service
+
+After configuring ingress sharding and Knative Serving, you can target a specific ingress shard in your Knative Service resources using a label.
+
+.Procedure
+
+* In your `Service` CR, add the label selector that matches a specific shard:
++
+.Example Service CR
+[source,yaml]
+----
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: hello-dev
+  labels:
+    router: dev # <1>
+spec:
+  template:
+    spec:
+      containers:
+      - image: docker.io/openshift/hello-openshift
+---
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: hello-prod
+  labels:
+    router: prod # <1>
+spec:
+  template:
+    spec:
+      containers:
+      - image: docker.io/openshift/hello-openshift
+  # ...
+----
+<1> The labels must match the configuration in the `KnativeServing` CR.
diff --git a/modules/verifying-serving-with-openshift-ingress-sharding-configuration.adoc b/modules/verifying-serving-with-openshift-ingress-sharding-configuration.adoc
@@ -0,0 +1,36 @@
+:_mod-docs-content-type: PROCEDURE
+[id="verifying-serving-with-openshift-ingress-sharding-configuration_{context}"]
+= Verifying Serving with OpenShift ingress sharding configuration
+
+After configuring ingress sharding, Knative Serving, and your service, you can verify that your service uses the correct route and the selected ingress shard.
+
+.Procedure
+
+. Print information about the services in the cluster by running the following command:
++
+[source,terminal]
+----
+$ oc get ksvc
+----
++
+.Example output
+[source,terminal]
+----
+NAME         URL                                                             LATESTCREATED      LATESTREADY        READY   REASON
+hello-dev    https://hello-dev-default.dev.serverless.cluster.example.com    hello-dev-00001    hello-dev-00001    True
+hello-prod   https://hello-prod-default.prod.serverless.cluster.example.com  hello-prod-00001   hello-prod-00001   True
+----
+
+. Verify that your service uses the correct route and the selected ingress shard by running the following command:
++
+[source,terminal]
+----
+$ oc get route -n knative-serving-ingress -o jsonpath='{range .items[*]}{@.metadata.name}{" "}{@.spec.host}{" "}{@.status.ingress[*].routerName}{"\n"}{end}'
+----
++
+.Example output
+[source,terminal]
+----
+route-19e6628b-77af-4da0-9b4c-1224934b2250-323461616533 hello-prod-default.prod.serverless.cluster.example.com ingress-prod
+route-cb5085d9-b7da-4741-9a56-96c88c6adaaa-373065343266 hello-dev-default.dev.serverless.cluster.example.com ingress-dev
+----