openshift · gabriel-rh · Nov 4, 2025 · Oct 27, 2025
diff --git a/gateways/ossm-about-gateways.adoc b/gateways/ossm-about-gateways.adoc
@@ -6,7 +6,11 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[] 
 
-A gateway is a standalone Envoy proxy deployment and an associated Kubernetes service operating at the edge of a service mesh. You can configure a gateway to provide fine-grained control over the traffic that enters or leaves the mesh. In {SMProductName}, you install gateways using gateway injection.
+[role="_abstract"]
+A gateway is a standalone Envoy proxy deployment and an associated Kubernetes service operating at the edge of a service mesh. You can configure a gateway to give fine-grained control over the traffic that enters or leaves the mesh. In {SMProductName}, you can install gateways by using gateway injection or via the Gateway API.
+
+{SMProductName} supports different gateway configurations based on the deployment mode. You can deploy gateways by using gateway injection and configure them with {istio} Gateway and `VirtualService` resources in sidecar mode or with {k8s} Gateway API resources in both sidecar and ambient modes.
 
 include::modules/ossm-about-gateway-injection.adoc[leveloffset=+1]
+
 include::modules/ossm-installing-gateway-using-gateway-injection.adoc[leveloffset=+2]
diff --git a/gateways/ossm-directing-outbound-traffic.adoc b/gateways/ossm-directing-outbound-traffic.adoc
@@ -10,8 +10,11 @@ toc::[]
 Using {istio} APIs, you can configure gateway proxies that were installed using gateway injection to direct traffic that is bound for an external service. 
 
 include::modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc[leveloffset=+1]
+
 include::modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc[leveloffset=+1]
+
 include::modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc[leveloffset=+1]
+
 include::modules/ossm-directing-egress-traffic-through-a-gateway-kubernetes-gateway-api-ambient-mode.adoc[leveloffset=+1]
 
 [role="_additional-resources-egress"]

diff --git a/gateways/ossm-getting-traffic-into-a-mesh.adoc b/gateways/ossm-getting-traffic-into-a-mesh.adoc
@@ -6,12 +6,42 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[] 
 
+[role="_abstract"]
 Using {istio} APIs, you can configure gateway proxies that were installed using gateway injection to accept traffic originating from outside the mesh, and route that traffic to the services within the mesh.
 
 You can expose gateway proxies to traffic outside a cluster by using either a `LoadBalancer` type `Service` or {ocp-short-name} `Routes`.
 
 include::modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc[leveloffset=+1]
-include::modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../gateways/ossm-about-gateways.adoc#ossm-about-gateway-injection_ossm-about-gateways[About gateway injection]
+
+include::modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* https://istio.io/latest/docs/reference/config/networking/gateway/#Gateway[Istio Gateway resource API reference (Istio documentation)]
+* https://istio.io/latest/docs/reference/config/networking/virtual-service/#VirtualService[VirtualService API reference (Istio documentation)]
+
 include::modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc[leveloffset=+1]
+
 include::modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc[leveloffset=+2]
-include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/networking/configuring-routes#nw-creating-a-route_route-configuration[Creating an HTTP-based Route]
+
+include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://kubernetes.io/docs/concepts/services-networking/gateway/[Kubernetes Gateway API concept (Kubernetes documentation)]
+
+include::modules/ossm-about-ingress-routing-ambient-mode.adoc[leveloffset=+1]
+
+include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc[leveloffset=+1]
diff --git a/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc b/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc
@@ -1,66 +1,21 @@
 // Module included in the following assemblies:
 
-// gateways/ossm-about-gateways.adoc
+// gateways/ossm-getting-traffic-into-a-mesh.adoc
 
 :_mod-docs-content-type: CONCEPT
 [id="ossm-about-configuring-a-gateway-to-accept-ingress-traffic_{context}"]
-= About configuring a gateway installed using gateway injection to accept ingress traffic
+= About ingress traffic routing approaches
 
-When you install a gateway using gateway injection you can configure it to receive ingress traffic using the {istio} `Gateway` and `VirtualService` resources in combination. The {istio} `Gateway` resource describes a load balancer operating at the edge of the mesh that receives incoming or outgoing HTTP/TCP connections. The `Gateway` specification describes a set of ports that should be exposed, the type of protocol to use, and the Server Name Indication (SNI) configuration for the load balancer. `VirtualServices` define routing rules to apply to an {istio} `Gateway`, similar to how you can use `VirtualServices` to define routing rules for internal mesh traffic.
+[role="_abstract"]
+{SMProductName} offers two approaches to configure ingress traffic routing to services in the mesh. The approach depends on the service mesh deployment mode and traffic management requirements.
 
-In the following example an {istio} `Gateway` resource configures a gateway proxy to act as an entry point for external traffic. This configuration exposes port 443 (HTTPS) for the host, `bookinfo.com`. The example configuration applies to pods with the `istio: ingressgateway` label. The `tls` mode is configured as `SIMPLE`, which terminates the incoming HTTPS traffic using the certificate and private key the example provides.
+Ingress routing with gateway injection and {istio} APIs::
+When you install a gateway by using gateway injection, you can configure it to receive ingress traffic by using the {istio} `Gateway` and `VirtualService` resources in combination.
 
-.Sample configuration
-[source,yaml,subs="attributes,verbatim"]
-----
-apiVersion: networking.istio.io/v1
-kind: Gateway
-metadata:
-  name: bookinfo-gateway
-  namespace: bookinfo
-spec:
-  selector:
-    istio: ingressgateway
-  servers:
-  - port:
-      number: 443
-      name: https-443
-      protocol: HTTPS
-    hosts:
-    - bookinfo.com
-    tls:
-      mode: SIMPLE
-      serverCertificate: /etc/certs/servercert.pem
-      privateKey: /etc/certs/privatekey.pem
-----
+The gateway injection approach is compatible with sidecar-based service mesh deployments where you enable sidecar injection in namespaces by using the `istio-injection=enabled` label or the `istio.io/rev=<revision>` label.
 
-The following `VirtualService` is bound to the {istio} `Gateway` resource shown in the previous example configuration. The specification defines rules to route traffic with the `/reviews/` path prefix to the reviews service in the `bookinfo` namespace. The `VirtualService` explicitly references the `Gateway` resource shown previously. This ensures that the routing rules are only applied to the traffic that enters through the specified gateway.
+Ingress routing with {k8s} Gateway API::
 
-.Sample configuration
-[source,yaml,subs="attributes,verbatim"]
-----
-kind: VirtualService
-metadata:
-  name: bookinfo-rule
-  namespace: bookinfo
-spec:
-  hosts:
-  - bookinfo.com
-  gateways:
-  - bookinfo/bookinfo-gateway
-  http:
-  - match:
-    - uri:
-        prefix: /reviews/
-    route:
-    - destination:
-        port:
-          number: 9080
-        host: reviews.bookinfo.svc.cluster.local
-----
+The {k8s} Gateway API provides a standardized approach for configuring ingress traffic routing using native {k8s} resources. With this approach, you use `Gateway` and `HTTPRoute` (or `GRPCRoute`) resources to configure how traffic enters the mesh and routes to services.
 
-[role="_additional-resources"]
-[id="ossm-about-configuring-gateways-additional-resources_{context}"]
-.Additional resources
-
-* xref:../gateways/ossm-about-gateways.adoc#ossm-about-gateway-injection_ossm-about-gateways[About gateway injection]
+While {istio} `Gateway` and `VirtualService` resources can be used for certain ingress use cases in ambient mode, the recommended approach is to use the {k8s} Gateway API, which provides full support and integration with ambient. You can also use the Gateway API with sidecar-based deployments.
diff --git a/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc b/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc
@@ -6,6 +6,7 @@
 [id="ossm-about-exposing-services-to-traffic-outside-a-cluster_{context}"]
 = About exposing services to traffic outside a cluster
 
+[role="_abstract"]
 To enable traffic from outside an {ocp-short-name} cluster to access services in a mesh, you must expose a gateway proxy by either setting its `Service` type to `LoadBalancer` or by using the {ocp-short-name} Router.
 
 Using Kubernetes load balancing to handle incoming traffic directly through the inbound gateway can reduce latency associated with data encryption. By managing encryption at the inbound gateway, you avoid the intermediate decryption and re-encryption steps within the mesh that often add latency. This approach allows mesh traffic to be encrypted and decrypted only once, which is generally more efficient.

diff --git a/modules/ossm-about-ingress-routing-ambient-mode.adoc b/modules/ossm-about-ingress-routing-ambient-mode.adoc
@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+
+// gateways/ossm-getting-traffic-into-a-mesh.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-ingress-routing-ambient-mode_{context}"]
+= About ingress traffic routing approaches in ambient mode
+
+[role="_abstract"]
+When using the {istio} ambient mode, you can use the {k8s} Gateway API to configure ingress traffic routing.
+
+Waypoint proxies for Layer 7 routing::
+You can deploy a waypoint proxy in the namespace that has your service to apply Layer 7 (L7) routing policies, such as path-based routing or header matching. In ambient mode, waypoint proxies process L7 traffic and enforce `HTTPRoute` and `GRPCRoute` rules.
+
+[IMPORTANT]
+====
+`VirtualService` resources are considered technology preview in ambient mode and should not be mixed with Gateway API configuration. The recommended approach in ambient mode is to use {k8s} Gateway API resources.
+====
diff --git a/...sm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc b/...sm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc
@@ -16,7 +16,7 @@ Use the {k8s} Gateway API to direct outbound HTTP traffic through an egress gate
 
 .Procedure
 
-. Optional: Enable the {k8} Gateway API custom resource definitions (CRDs). 
+. Optional: Enable the {k8s} Gateway API custom resource definitions (CRDs). 
 +
 [NOTE]
 ====

diff --git a/...m-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc b/...m-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc
@@ -5,6 +5,7 @@
 [id="ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes_{context}"]
 = Exposing a gateway to traffic outside the cluster by using OpenShift Routes
 
+[role="_abstract"]
 You can expose a gateway to traffic outside the cluster by using {ocp-short-name} Routes. This approach provides an alternative to using Kubernetes load balancer service when you have to expose gateways to traffic outside the cluster.
 
 .Prerequisites
@@ -22,7 +23,7 @@ $ oc patch service <gateway_name> -n <gateway_namespace> -p '{"spec": {"type": "
 
 . Create a YAML file named `httpbin-route.yaml` that defines a `Route` for the `httpbin` service.
 +
-[source,yaml,subs="attributes,verbatim"]
+[source,yaml]
 ----
 apiVersion: route.openshift.io/v1
 kind: Route
@@ -70,10 +71,4 @@ $ INGRESS_HOST=$(oc get service router-default -n openshift-ingress -o jsonpath=
 $ curl -s -I -H Host:httpbin.example.com http://$INGRESS_HOST/headers
 ----
 
-. Verify that the response has the `HTTP/1.1 200 OK` status, which indicates that the request was successful.
-
-[role="_additional-resources"]
-[id="ossm-exposing-gateway-outside-cluster-additional-resources_{context}"]
-.Additional resources
-
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/networking/configuring-routes#nw-creating-a-route_route-configuration[Creating an HTTP-based Route]
+. Verify that the response has the `HTTP/1.1 200 OK` status, which indicates that the request was successful.
-Original file line number
+Diff line change
@@ Expand Up @@
     .Procedure
-    . Optional: Enable the {k8} Gateway API custom resource definitions (CRDs).
+    . Optional: Enable the {k8s} Gateway API custom resource definitions (CRDs).
     +
     [NOTE]
     ====
@@ Expand Down @@