diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 75290a1547bd..f5074bfdf13a 100644 --- 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 new file mode 100644 index 000000000000..e24657dcd4c3 --- /dev/null +++ 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 new file mode 100644 index 000000000000..fa525d4eb75a --- /dev/null +++ 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 new file mode 100644 index 000000000000..3c7eac09d807 --- /dev/null +++ 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 new file mode 100644 index 000000000000..ddd11d398fd7 --- /dev/null +++ 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 new file mode 100644 index 000000000000..b9e328e46ad6 --- /dev/null +++ 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 +----