OSDOCS-18134: JTBD Docs Enhancement Gateway API Routing

_topic_maps/_topic_map.yml

@@ -1792,6 +1792,8 @@ Topics:
       File: ingress-controller-dnsmgt
     - Name: Gateway API with OpenShift Container Platform networking
       File: ingress-gateway-api
+    - Name: Routing HTTP requests to services
+      File: routing-http-requests-to-services
   - Name: Load balancing on OpenStack
     File: load-balancing-openstack
   - Name: Load balancing with MetalLB

modules/applying-processing-filters-http-requests.adoc

@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress_load_balancing/configuring_ingress_cluster_traffic/routing-http-requests-to-services.adoc
+//
+:_mod-docs-content-type: PROCEDURE
+[id="applying-processing-filters-http-requests_{context}"]
+= Apply processing filters to HTTP requests
+
+[role="_abstract"]
+To modify how HTTP requests are processed before they reach your backend services, you can pre-configure filters within the rules of your `HTTPRoute` custom resource (CR). Configuring these filters allows you to automatically redirect traffic, modify headers, or mirror requests to achieve your desired routing behavior.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have installed the {oc-first}.
+
+.Procedure
+
+. Create or edit an `HTTPRoute` YAML file to include your desired processing directives under the `spec.rules.filters` field. 
++
+--
+The following example demonstrates a complete `HTTPRoute` custom resource (CR) with a `requestRedirect` filter that issues a permanent redirect (301) from HTTP to HTTPS. For details on configuring other filter types, see xref:supported-httproute-filters_{context}[].
+
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: <http_filter_example>
+  namespace: <example_application>
+spec:
+  parentRefs:
+  - name: <example_gateway>
+    namespace: openshift-ingress
+  hostnames:
+  - "<example.com>"
+  rules:
+  - filters:
+    - type: RequestRedirect
+      requestRedirect:
+        scheme: https
+        statusCode: 301
+----
+--
+
+. Apply the `HTTPRoute` CR by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----

modules/comparing-openshift-routes-and-httproutes.adoc

@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress_load_balancing/configuring_ingress_cluster_traffic/routing-http-requests-to-services.adoc
+//
+:_mod-docs-content-type: REFERENCE
+[id="comparing-openshift-routes-and-httproutes_{context}"]
+= {product-title} routes and HTTPRoutes Comparison
+
+[role="_abstract"]
+When you migrate from standard networking to the Gateway API, you can compare {product-title} routes with `HTTPRoute` custom resources (CRs) to understand which features are supported and how your configuration must change. While both resources handle ingress traffic, they have distinct feature sets and implementation differences.
+
+The following features are exclusive to `HTTPRoute` CRs:
+
+* Multiple hostnames
+* Matching based on HTTP headers
+* Matching based on query parameters
+* Request header modification
+* Request redirection
+* Request mirroring
+
+The following features are exclusive to {product-title} routes:
+
+* IP allow lists
+* Rate limiting (connection-based)
+* Subdomain indication
+* Re-encrypt TLS termination
+* Passthrough TLS termination
+
+The following table outlines the features that are shared between both resources and how their specific implementations differ:
+
+.Shared features and implementation differences
+[cols="1,1,1",options="header"]
+|===
+|Feature |{product-title} route implementation |`HTTPRoute` implementation
+
+|Path matching
+|Supports prefix and exact matching.
+|Supports prefix, exact, and regular expression matching.
+
+|Backend references
+|Supports weighted traffic delivery to services.
+|Supports weighted traffic delivery to services via `backendRefs`.
+
+|Rewrite target
+|Configured using the `haproxy.router.openshift.io/rewrite-target` annotation.
+|Configured using the `URLRewrite` filter.
+
+|Sharding
+|Configured using metadata labels.
+|Configured using parent references (`parentRefs`).
+|===

modules/configuring-http-request-matching-conditions.adoc

@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress_load_balancing/configuring_ingress_cluster_traffic/routing-http-requests-to-services.adoc
+//
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-http-request-matching-conditions_{context}"]
+= Configure HTTP request matching conditions
+
+[role="_abstract"]
+To ensure traffic is routed to the correct application when multiple services share a gateway, you can define request matching conditions within your `HTTPRoute` custom resource (CR). You can match HTTP requests based on paths, headers, query parameters, or methods.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have installed the {oc-first}.
+
+.Procedure
+
+. Create or edit an `HTTPRoute` YAML file to include your desired match conditions under the `spec.rules.matches` field. 
++
+--
+The following example demonstrates a complete `HTTPRoute` custom resource (CR) configured with path-based matching to route requests for `/<example_app>` to a backend service. For details on configuring other match types, see xref:supported-httproute-match-types_{context}[].
+
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: <path_match_example>
+  namespace: <example_application>
+spec:
+  parentRefs:
+  - name: <example_gateway>
+    namespace: openshift-ingress
+  hostnames:
+  - "<example.com>"
+  rules:
+  - matches:
+    - path:
+        type: Exact
+        value: /<example_app>
+    backendRefs:
+    - name: <example_backend>
+      port: 8080
+----
+--
+
+. Apply the `HTTPRoute` CR by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----

modules/configuring-routing-destinations-weights.adoc

@@ -0,0 +1,47 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress_load_balancing/configuring_ingress_cluster_traffic/routing-http-requests-to-services.adoc
+//
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-routing-destinations-weights_{context}"]
+= Configure routing destinations and traffic weights
+
+[role="_abstract"]
+To route traffic to your backends, you must define service destinations and traffic weights within your `HTTPRoute` custom resource (CR) to distribute requests across your applications. 
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have installed the {oc-first}.
+
+.Procedure
+
+. Create or edit an `HTTPRoute` YAML file to include your desired service destinations under the `spec.rules.backendRefs` field.
++
+--
+The following example demonstrates a complete `HTTPRoute` custom resource (CR) with a single backend destination that routes traffic to a service named `<service_v1>`. For details on configuring weights and routing to multiple destinations, see xref:httproute-backendref-configuration_{context}[].
+
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: <backend_route_example>
+  namespace: <example_application>
+spec:
+  parentRefs:
+  - name: <example_gateway>
+    namespace: openshift-ingress
+  rules:
+  - backendRefs:
+    - name: <service_v1>
+      port: 8080
+----
+--
+
+. Apply the `HTTPRoute` CR by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----

modules/httproute-backendref-configuration.adoc

@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress_load_balancing/configuring_ingress_cluster_traffic/routing-http-requests-to-services.adoc
+//
+:_mod-docs-content-type: REFERENCE
+[id="httproute-backendref-configuration_{context}"]
+= HTTPRoute backendRef configuration
+
+[role="_abstract"]
+BackendRefs are the service destinations of requests that meet your matches rules, and are composed of group, kind, name, namespace, port, and weight[cite: 64]. Name and port are the only required fields and refer to the service name and the service port number[cite: 65]. Weight is relevant when there is more than one backendRef, and specifies the proportion of requests forwarded to that specific backendRef[cite: 66]. Without a backendRef, the rule doesn’t do any request forwarding and may return an error[cite: 67].
+
+== Example: Single backend destination
+
+This example shows a BackendRef where there is a single backend destination, a service named `<service_v1>`[cite: 68]:
+
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: <backend_route_example>
+  namespace: <example_application>
+spec:
+  parentRefs:
+  - name: <example_gateway>
+    namespace: openshift-ingress
+  rules:
+  - backendRefs:
+    - name: <service_v1>
+      port: 8080
+----
+* `backendRefs` defines the destination services for the traffic.
+* `name` specifies the name of the Kubernetes service.
+* `port` specifies the port on which the service is listening.
+
+== Example: Weighted backend delivery
+
+This example shows two backendRefs where there is weighted delivery of 15 and 25 for the backends[cite: 70]. This means `<service_v1>` gets 15/40 (3/8ths) of the traffic, and `<service_v2>` gets 25/40 (5/8ths) of the traffic[cite: 70]. Though not required, it is recommended to have the weights add up to 100 whenever possible for clarity[cite: 71].
+
+[source,yaml]
+----
+spec:
+  rules:
+  - backendRefs:
+    - name: <service_v1>
+      port: 8080
+      weight: 15
+    - name: <service_v2>
+      port: 8080
+      weight: 25
+----

modules/httproute-timeout-configuration.adoc

@@ -0,0 +1,73 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress_load_balancing/configuring_ingress_cluster_traffic/routing-http-requests-to-services.adoc
+//
+:_mod-docs-content-type: REFERENCE
+[id="httproute-timeout-configuration_{context}"]
+= HTTPRoute timeout configuration
+
+[role="_abstract"]
+There are two types of timeouts you can configure for an `HTTPRoute` custom resource (CR): `request` and `backendRequest`.
+
+The `request` timeout covers the total time to send a request and then get a response back to the client. It represents the duration of the entire request-response transaction. 
+
+The `backendRequest` timeout covers the time for a request to travel from the gateway to the backend, and for a response to be received. Extending the timeout for a `backendRequest` can be helpful if the gateway needs to retry connections to a backend.
+
+[NOTE]
+====
+The `backendRequest` timeout is classified as an extended feature (`Support: Extended`) according to Gateway API conventions.
+====
+
+When configuring timeouts, you must adhere to the following formatting rules and constraints:
+
+* The value of a `backendRequest` timeout cannot be greater than the value of the `request` timeout.
+* If specified, a timeout value must be `0` or greater than or equal to `1ms`. 
+* A zero-valued timeout (`0`) means there is no timeout.
+* Timeouts use a string format that starts with a number and expresses hours (`h`), minutes (`m`), seconds (`s`), or milliseconds (`ms`).
+* The number can be up to five digits, such as `10000s`. 
+* You can use multipart durations to express fractions, such as `1m30s`, but you cannot use decimal dots.
+
+== Example: Request timeout
+
+The following example demonstrates a complete `HTTPRoute` custom resource (CR) where the entire request must complete within 30 seconds:
+
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: <timeout_example>
+  namespace: <example_application>
+spec:
+  parentRefs:
+  - name: <example_gateway>
+    namespace: openshift-ingress
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /<timeout_path>
+    timeouts:
+      request: 30s
+    backendRefs:
+    - name: <example_service>
+      port: 8080
+----
+* `request` specifies the timeout for the full request-response cycle.
+* `PathPrefix` ensures the timeout applies to all requests starting with `/<timeout_path>`.
+
+== Example: Request and backendRequest timeouts
+
+The following snippet demonstrates a configuration where the request must succeed within 5 seconds, and the gateway-to-backend hop must complete within 1 second:
+
+[source,yaml]
+----
+spec:
+  rules:
+  - timeouts:
+      request: 5s
+      backendRequest: 1s
+    backendRefs:
+    - name: <example_service>
+      port: 8080
+----