[service-mesh-docs-3.2] OSSM-11013 [DOCS] Review and update Egress docs for ambient mode

gateways/ossm-directing-outbound-traffic.adoc

@@ -6,8 +6,17 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[] 
 
+[role="_abstract"]
 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-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"]
+.Additional resources
+
+* link:https://istio.io/latest/docs/tasks/traffic-management/egress/egress-gateway/[Egress gateways (Istio documentation)]
+
+* link:https://gateway-api.sigs.k8s.io/[Introduction (Gateway API documentation)]

modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc

@@ -5,8 +5,24 @@
 [id="ossm-about-directing-egress-traffic-through-a-gateway_{context}"]
 = About directing egress traffic through a gateway
 
-You can configure a gateway installed using gateway injection as an exit point for the traffic leaving a service mesh. In this configuration, the gateway acts as a forward proxy for requests sent to the services that are external to the mesh. 
+[role="_abstract"]
+You can configure a gateway installed through gateway injection as an exit point for traffic leaving the service mesh. It acts as a forward proxy for requests sent to services external to the mesh.
 
-Configuring a gateway for egress traffic can help fulfill security requirements. For example, an egress gateway can be used in environments where traffic restrictions require that all traffic exiting a mesh flows through a dedicated set of nodes. Similarly, a gateway can be used when network policies prevent application nodes from directly accessing external services. In such scenarios, gateway proxies are deployed on dedicated egress nodes capable of accessing external services. These nodes can then be subjected to strict network policy enforcement or additional monitoring to enhance security.
+Egress gateway:: An egress gateway is configured as an exit point for traffic leaving the service mesh, acting as a forward proxy for requests sent to external services. You can configure an egress gateway to fulfill security requirements:
 
-To configure a gateway installed using gateway injection to direct the egress traffic, use a combination of the {istio} `ServiceEntry`, `Gateway`, `VirtualService`, and `DestinationRule` resources. Use the `ServiceEntry` resource to define the properties of an external service. The external service is added to the {istio} service registry for the mesh. This enables you to apply {istio} features, such as monitoring and routing rules, to the traffic exiting the mesh that is destined for an external service. Use the `Gateway`, `VirtualService`, and `DestinationRule` resources to set up rules that route traffic from the mesh to the external service using the gateway proxy.
+* Traffic Restrictions: In environments with strict traffic restrictions, an egress gateway ensures all outbound traffic flows through a dedicated set of nodes.
+
+* Network Policy Enforcement: When network policies prevent application nodes from directly accessing external services, the egress gateway handles the external access.
+
++
+In these scenarios, gateway proxies are deployed on dedicated egress nodes capable of accessing external services. These nodes can then be subjected to strict network policy enforcement or additional monitoring to enhance security.
+
+Configure egress traffic:: You can configure a gateway installed through gateway injection to direct the egress traffic by combining the following {istio} resources:
+
+* Use the `ServiceEntry` resource to define the properties of an external service. The external service is added to the {istio} service registry for the mesh, which enables you to apply {istio} features, such as monitoring and routing rules, to the traffic exiting the mesh that is destined for an external service.
+
+* Use the `Gateway`, `VirtualService`, and `DestinationRule` resources to set up rules that route traffic from the mesh to the external service using the gateway proxy.
+
+Egress routing in ambient mode:: If your deployment uses ambient mode, you must configure egress routing using the {k8s} Gateway API instead of {istio} `Gateway` and `VirtualService` resources. The {k8s} Gateway API provides a standardized, {k8s}-native method for defining how traffic exits the mesh and reaches external services.
++
+You can use `Gateway` and `HTTPRoute` (or `GRPCRoute`) resources to control how mesh traffic is routed to destinations outside the cluster. The Gateway API is fully supported in ambient mode and can also be used with sidecar-based deployments, providing a consistent configuration model for both ingress and egress routing.

modules/ossm-directing-egress-traffic-through-a-gateway-kubernetes-gateway-api-ambient-mode.adoc

@@ -0,0 +1,142 @@
+// This procedure is used in the following assembly:
+// * service-mesh-docs-main/gateways/ossm-directing-outbound-traffic-through-a-gateway
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-directing-egress-traffic-through-gateway-kubernetes-gateway-api-ambient-mode_{context}"]
+= Directing egress traffic through a gateway using the {k8s} Gateway API in ambient mode
+
+[role="_abstract"]
+Use the {k8s} Gateway API and waypoint proxy to direct outbound HTTP traffic through an egress gateway.
+
+.Prerequisites
+
+* You have installed the {SMProduct} Operator version 3.2 or later.
+
+* You configured the `Istio` and `IstioCNI` resources with ambient profile.
+
+* You have created a `Ztunnel` resource.
+
+.Procedure
+
+. Optional: Enable the {k8} Gateway API custom resource definitions (CRDs). 
++
+[NOTE]
+====
+As of {k8s} 1.28 and {ocp-product-title} 4.18 or earlier version of {product-title}, the {k8s} Gateway API CRDs are not available by default and you must install the CRDs before you can use them. {ocp-product-title} 4.19 and later versions install the CRDs by default.
+====
+
+. Create a namespace called `egress-gateway` by running the following command:
++
+[source,terminal]
+----
+$ oc create namespace egress-gateway
+----
+
+. Apply the ambient mode label to the namespace by running the following command:
++
+[source,terminal]
+----
+$ oc label namespace egress-gateway istio.io/dataplane-mode=ambient
+----
+
+. Create a YAML file named `egress-se.yaml` that defines the `ServiceEntry`.
++
+[source,yaml]
+----
+apiVersion: networking.istio.io/v1
+kind: ServiceEntry
+metadata:
+  name: httpbin-ext
+  namespace: egress-gateway
+  labels:
+    istio.io/use-waypoint: waypoint
+spec:
+  hosts:
+  - httpbin.org
+  ports:
+  - number: 80
+    name: http
+    protocol: HTTP
+  resolution: DNS
+----
+
+.. Apply the YAML file by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f egress-se.yaml
+----
+
+.. Create a YAML file named `waypoint.yaml` that creates a waypoint proxy in `egress-gateway` namespace similar to the following example:
++
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: waypoint
+  namespace: egress-gateway
+  labels:
+    istio.io/gateway-for: service
+spec:
+  gatewayClassName: istio-waypoint
+  listeners:
+  - name: mesh
+    port: 15008
+    protocol: HBONE
+----
+
+.. Apply the YAML file by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f waypoint.yaml
+----
+
+[NOTE]
+====
+As an alternate to creating the `waypoint.yaml` YAML file, you can also set up waypoint proxy by running the following command:
+[source,terminal]
+----
+$ istioctl waypoint apply --enroll-namespace --name waypoint --namespace egress-gateway
+----
+When you use the `--enroll-namespace` option, all services in the `egress-gateway` namespace (including `ServiceEntries`), will route their traffic through the waypoint.
+====
+
+.Verification
+
+. Verify the status of the gateway configuration by running the following command:
++
+[source,terminal]
+----
+$ oc get gateways.gateway.networking.k8s.io waypoint -n egress-gateway
+----
++
+The `PROGRAMMED` column shows `True` when the configuration succeeds, similar to the following example:
++
+[source,terminal]
+----
+NAME       CLASS            ADDRESS          PROGRAMMED   AGE
+waypoint   istio-waypoint   172.30.227.148   True         9s
+----
+
+. Create a `curl` pod in the `egress-gateway` namespace by running the following command:
++
+[source,terminal]
+----
+$ oc run test-pod --image=curlimages/curl:latest -n egress-gateway --rm -it --restart=Never -- sh
+----
+
+. By using the `curl` client, verify that you can access `httpbin.org` through the egress gateway by running the following command:
++
+[source,terminal]
+----
+$ curl -v http://httpbin.org/get
+----
++
+The output shows a response from `httpbin.org` service that indicates egress traffic routes through the configured gateway. The ztunnel logs should show traffic routed through the waypoint. The terminal should display information similar to the following output:
++
+[source,terminal]
+----
+2025-10-24T08:08:35.242159Z info access connection complete src.addr=[fd01:0:0:5::b0]:56288 src.workload="test-pod" src.namespace="egress-gateway" src.identity="spiffe://cluster.local/ns/egress-gateway/sa/default" dst.addr=[fd01:0:0:5::af]:15008 dst.hbone_addr=[2001:2::2]:80 dst.service="httpbin.org" dst.workload="waypoint-5b668759d5-vrnx8" dst.namespace="egress-gateway" dst.identity="spiffe://cluster.local/ns/egress-gateway/sa/waypoint" direction="outbound" bytes_sent=78 bytes_recv=540 duration="957ms"
+----

modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc

@@ -5,6 +5,7 @@
 [id="ossm-directing-egress-traffic-through-a-gateway-using-istio-apis_{context}"]
 = Directing egress traffic through a gateway using Istio APIs
 
+[role="_abstract"]
 Use {istio} APIs to direct outbound HTTP traffic through a gateway that was installed using gateway injection.
 
 .Prerequisites
@@ -69,7 +70,6 @@ $ export CURL_POD=$(oc get pod -n curl -l app=curl -o jsonpath='{.items[0].metad
 
 . Create a YAML file named `http-se.yaml` that directs traffic from the mesh to an external service. The following example defines a `ServiceEntry` for a URL.
 +
-.Example configuration
 [source,yaml,subs="attributes,verbatim"]
 ----
 apiVersion: networking.istio.io/v1
@@ -106,7 +106,6 @@ This command should return HTTP status codes, such as `301` (redirect) or `200`
 
 . Create a YAML file named `http-gtw.yaml` that creates an egress `Gateway` and routes traffic from the mesh to the host specified for the external service.
 +
-.Example configuration
 [source,yaml,subs="attributes,verbatim"]
 ----
 apiVersion: networking.istio.io/v1alpha3
@@ -145,7 +144,6 @@ $ oc apply -f http-gtw.yaml
 
 . Create a YAML file named `http-vs.yaml` that sets up a `VirtualService` to manage the flow of traffic from the application sidecars through the egress gateway to the external host.
 +
-.Example configuration
 [source,yaml,subs="attributes,verbatim"]
 ----
 apiVersion: networking.istio.io/v1alpha3
@@ -199,7 +197,6 @@ $ oc exec "$CURL_POD" -n curl -c curl -- curl -sSL -o /dev/null -D - http://docs
 +
 The terminal should display information similar to the following output:
 +
-.Example output
 [source,terminal]
 ----
 ...
@@ -226,7 +223,6 @@ Access logging must be enabled for this verification step to work. You can enabl
 +
 The terminal should display information similar to the following output:
 +
-.Example output
 [source,terminal]
 ----
 [2024-11-07T14:35:52.428Z] "GET / HTTP/2" 301 - via_upstream - "-" 0 0 24 24 "10.128.2.30" "curl/8.11.0" "79551af2-341b-456d-b414-9220b487a03b" "docs.redhat.com" "23.55.176.201:80" outbound|80||docs.redhat.com 10.128.2.29:49766 10.128.2.29:80 10.128.2.30:38296 -

modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc

@@ -5,6 +5,7 @@
 [id="ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api_{context}"]
 = Directing egress traffic through a gateway by using the {k8s} Gateway API
 
+[role="_abstract"]
 Use the {k8s} Gateway API to direct outbound HTTP traffic through an egress gateway.
 
 .Prerequisites
@@ -19,12 +20,11 @@ Use the {k8s} Gateway API to direct outbound HTTP traffic through an egress gate
 +
 [NOTE]
 ====
-As of {k8s} 1.28 and {ocp-product-title} 4.18 or earlier version of {product-title}, the {k8s} Gateway API CRDs are not available by default and you must enabled the CRDs before you can use them. {ocp-product-title} 4.19 and later versions enable the CRDs by default.
+As of {k8s} 1.28 and {ocp-product-title} 4.18 or earlier version of {product-title}, the {k8s} Gateway API CRDs are not available by default and you must install the CRDs before you can use them. {ocp-product-title} 4.19 and later versions install the CRDs by default.
 ====
 
 .. Create a YAML file named `gateway-cr.yaml` that enables the Kubernetes Gateway API CRDs. 
 +
-.Example {k8s} Gateway Custom Resource (CR) file
 [source,yaml,subs="attributes,verbatim"]
 ----
 apiVersion: gateway.networking.k8s.io/v1
@@ -93,7 +93,6 @@ $ oc label namespace egress-gateway istio-injection=enabled
 
 . Create a YAML file named `egress-gateway-cr.yaml` that defines the egress gateway.
 +
-.Example egress gateway CR file
 [source,yaml,subs="attributes,verbatim"]
 ----
 # ServiceEntry to allow traffic to httpbin.org
@@ -194,12 +193,4 @@ $ oc run test-pod --image=curlimages/curl:latest -n egress-gateway --rm -it --re
 $ curl -v http://httpbin.org/get
 ----
 +
-Desired output shows a response from `httpbin.org` that indicates egress traffic routes through the configured gateway.
-
-[role="_additional-resources-egress"]
-.Additional resources
-
-* link:https://istio.io/latest/docs/tasks/traffic-management/egress/egress-gateway/[Egress gateways] (Istio documentation)
-
-* link:https://gateway-api.sigs.k8s.io/[Introduction] (Gateway API documentation)
-
+Desired output shows a response from `httpbin.org` that indicates egress traffic routes through the configured gateway.