OSSM-11147 Istio Ambient mode waypoint docs: Waypoint proxy

_attributes/common-attributes.adoc

@@ -108,4 +108,3 @@
 :JaegerVersion: 1.47.0
 //CLI
 :oc-first: pass:quotes[OpenShift CLI (`oc`)]
-

install/ossm-istio-ambient-mode.adoc

@@ -6,12 +6,13 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-{istio} ambient mode introduces an architecture for {SMProductName} without sidecar injection. This mode is designed to simplify operations and reduce resource usage. Instead of injecting a sidecar proxy into each application pod, ambient mode uses a shared node-level proxy for Layer 4 (L4) functionality and an optional, dedicated proxy for Layer 7 (L7) features.
+{istio} ambient mode introduces an architecture for {SMProductName} without sidecar injection. The {istio} ambient mode is designed to simplify operations and reduce resource usage. Instead of injecting a sidecar proxy into each application pod, ambient mode uses a shared node-level proxy for Layer 4 (L4) functionality and an optional, dedicated proxy for Layer 7 (L7) features.
 
 include::snippets/technology-preview-istio-ambient-mode.adoc[]
 
 include::modules/ossm-about-istio-ambient-mode.adoc[leveloffset=+1]
-include::modules/ossm-installing-istio-ambient-mode.adoc[leveloffset=+2]
+
+include::modules/ossm-installing-istio-ambient-mode.adoc[leveloffset=+1]
 
 .Next steps
 * xref:../install/ossm-istio-ambient-mode.adoc#ossm-scoping-sm-discovery-selectors-istio-ambient-mode_ossm-istio-ambient-mode[Scoping Service Mesh with discovery selectors in Istio ambient mode]
@@ -25,14 +26,24 @@ include::modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc[leveloff
 * xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping the mesh with discovery selectors]
 
 include::modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc[leveloffset=+2]
+
 include::modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 * xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-about-bookinfo-application_ossm-installing-openshift-service-mesh[About the Bookinfo application]
 
+include::modules/ossm-about-istio-ambient-waypoint.adoc[leveloffset=+1]
+
+include::modules/ossm-deploying-waypoint-using-gateway-api.adoc[leveloffset=+1]
+
+include::modules/ossm-deploying-waypoint-proxy.adoc[leveloffset=+1]
+
+include::modules/ossm-enabling-cross-namespace-waypoint-usage.adoc[leveloffset=+1]
+
 [role="_additional-resources"]
 [id="additional-resources_{context}"]
 == Additional resources
 * link:https://istio.io/latest/docs/ambient/architecture/[Ambient mode architecture (Istio documentation)]
-* link:https://istio.io/latest/docs/ambient/usage/add-workloads/[Adding workloads to a mesh in ambient mode (Istio documentation)]
+* link:https://istio.io/latest/docs/ambient/usage/add-workloads/[Adding workloads to a mesh in ambient mode (Istio documentation)]
+* link:https://istio.io/latest/docs/ambient/usage/waypoint/#waypoint-traffic-types[Waypoint traffic types (Istio documentation)]

modules/ossm-about-istio-ambient-waypoint.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+
+// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-istio-ambient-waypoint_{context}"]
+= About waypoint proxies in Istio ambient mode
+
+After setting up {istio} ambient mode with ztunnel proxies, you can add waypoint proxies to enable advanced Layer 7 (L7) processing features that {istio} provides.
+
+{istio} ambient mode separates the functionality of {istio} into two layers:
+
+* A secure Layer 4 (L4) overlay managed by ztunnel proxies
+
+* An L7 layer managed by optional waypoint proxies
+
+A waypoint proxy is an Envoy-based proxy that performs L7 processing for workloads running in ambient mode. It functions as a gateway to a resource such as a namespace, service, or pod. You can install, upgrade, and scale waypoint proxies independently of applications. The configuration uses the {k8s} Gateway API.
+
+Unlike the sidecar model, where each workload runs its own Envoy proxy, waypoint proxies reduce resource use by serving multiple workloads within the same security boundary, such as all workloads in a namespace.
+
+A destination waypoint enforces policies by acting as a gateway. All incoming traffic to a resource—namespace, service, or pod—passes through the waypoint for policy enforcement.
+
+The `ztunnel` node proxy manages L4 functions in ambient mode, including mutual Transport Layer Security (mTLS) encryption, L4 traffic processing, and telemetry. Ztunnel and waypoint proxies communicate using HBONE (HTTP-Based Overlay Network), a protocol that tunnels traffic over HTTP/2 CONNECT with mutual TLS (mTLS) on port `15008`.
+
+You can add a waypoint proxy if workloads require any of the following L7 capabilities:
+
+Traffic management:: Advanced HTTP routing, load balancing, circuit breaking, rate limiting, fault injection, retries, and timeouts
+
+Security:: Authorization policies based on L7 attributes such as request type or HTTP headers
+
+Observability:: HTTP metrics, access logging, and tracing for application traffic

modules/ossm-deploying-waypoint-proxy.adoc

@@ -0,0 +1,92 @@
+// Module included in the following assemblies:
+
+// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-deploying-waypoint-proxy_{context}"]
+= Deploying a waypoint proxy
+
+You can deploy a waypoint proxy in the `bookinfo` application namespace to route traffic through the {istio} ambient data plane and enforce L7 policies.
+
+.Prerequisites
+
+* You have logged in to the {ocp-product-title} 4.19 or later, which provides supported {k8s} Gateway API custom resource definitions (CRDs) required for ambient mode functionality.
+
+* You have the {SMProductName} Operator 3.2.0 or later installed on the OpenShift cluster.
+
+* You have {istio} deployed in ambient mode.
+
+* You have deployed the `bookinfo` sample application for the following example.
+
+* You have added the `label istio.io/dataplane-mode=ambient` to the target namespace.
+
+.Procedure
+
+. Deploy a waypoint proxy in the `bookinfo` application namespace similar to the following example:
++
+.Example configuration
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  labels:
+    istio.io/waypoint-for: service
+  name: waypoint
+  namespace: bookinfo
+spec:
+  gatewayClassName: istio-waypoint
+  listeners:
+  - name: mesh
+    port: 15008
+    protocol: HBONE
+----
+
+. Apply the `waypoint` custom resource (CR) by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f waypoint.yaml
+----
++
+The `istio.io/waypoint-for: service` label indicates that the waypoint handles traffic for services. The label determines the type of traffic processed. For more information, see "Waypoint traffic types".
+
+. Enroll the `bookinfo` namespace to use the waypoint by running the following command:
++
+[source,terminal]
+----
+$ oc label namespace bookinfo istio.io/use-waypoint=waypoint
+----
+
+After enrolling the namespace, requests from any pods using the ambient data plane to services in bookinfo will route through the waypoint for L7 processing and policy enforcement.
+
+.Verification
+
+. Confirm that the waypoint proxy is used by all the services in the `bookinfo` namespace by running the following command:
++
+[source,terminal]
+----
+$ istioctl ztunnel-config svc --namespace ztunnel
+----
++
+.Example output
+[source,termional]
+----
+NAMESPACE    SERVICE NAME     SERVICE VIP     WAYPOINT   ENDPOINTS
+bookinfo     details          172.30.15.248   waypoint   1/1
+bookinfo     details-v1       172.30.114.128  waypoint   1/1
+bookinfo     productpage      172.30.155.45   waypoint   1/1
+bookinfo     productpage-v1   172.30.76.27    waypoint   1/1
+bookinfo     ratings          172.30.24.145   waypoint   1/1
+bookinfo     ratings-v1       172.30.139.144  waypoint   1/1
+bookinfo     reviews          172.30.196.50   waypoint   3/3
+bookinfo     reviews-v1       172.30.172.192  waypoint   1/1
+bookinfo     reviews-v2       172.30.12.41    waypoint   1/1
+bookinfo     reviews-v3       172.30.232.12   waypoint   1/1
+bookinfo     waypoint         172.30.92.147   None       1/1
+----
+
+[NOTE]
+====
+You can also configure only specific services or pods to use a waypoint by labeling the respective service or pod. When enrolling a pod explicitly, also add the `istio.io/waypoint-for: workload` label to the corresponding `gateway` resource.
+====

modules/ossm-deploying-waypoint-using-gateway-api.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+
+// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-deploying-waypoint-using-gateway-api_{context}"]
+= Deploying waypoint proxies using gateway API
+
+You can deploy waypoint proxies using {k8s} Gateway resource.
+
+.Prerequisites
+
+* You have logged in to the {ocp-product-title} 4.19 or later, which provides supported {k8s} Gateway API CRDs required for ambient mode functionality.
+
+* You have the {SMProductName} Operator 3.2.0 or later installed on the OpenShift cluster.
+
+* You have {istio} deployed in ambient mode.
+
+* You have applied the required labels to workloads or namespaces to enable `ztunnel` traffic redirection.
+
+[IMPORTANT]
+====
+{istio} ambient mode is not compatible with clusters that use {SMProductName} 2.6 or earlier. You must not deploy both versions in the same cluster.
+====
+
+.Procedure
+
+* On {ocp-product-title} 4.18 and earlier, install the community-maintained {k8s} Gateway API CRDs by running the following command:
++
+[source,terminal]
+----
+$ oc get crd gateways.gateway.networking.k8s.io &> /dev/null || \
+  { oc apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml; }
+----
++
+From {ocp-product-title} 4.19 onwards, the Gateway API CRDs are installed by default.
+
+[NOTE]
+====
+The CRDs are community maintained and not supported by Red Hat. Upgrading to {ocp-product-title} 4.19 or later, which includes supported Gateway API CRDs, may disrupt applications.
+====

modules/ossm-enabling-cross-namespace-waypoint-usage.adoc

@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+
+// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-enabling-cross-namespace-waypoint-usage_{context}"]
+= Enabling cross-namespace waypoint usage
+
+You can use a cross-namespace waypoint to allow resources in one namespace to route traffic through a waypoint deployed in a different namespace.
+
+.Procedure
+
+. Create a `Gateway` resource that allows workloads in the `bookinfo` namespace to use the `waypoint-default` from the `default` namespace similar to the following example:
++
+.Example configuration
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: waypoint-default
+  namespace: default
+spec:
+  gatewayClassName: istio-waypoint
+  listeners:
+  - name: mesh
+    port: 15008
+    protocol: HBONE
+    allowedRoutes:
+      namespaces:
+        from: Selector
+        selector:
+          matchLabels:
+            kubernetes.io/metadata.name: bookinfo
+----
+
+. Apply the cross-namespace waypoint by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f waypoint-default.yaml
+----
+
+. Add the labels required to use a cross-namespace waypoint:
+
+.. Add the `istio.io/use-waypoint-namespace` label to specify the namespace where the waypoint resides by running the following command:
++
+[source,terminal]
+----
+$ oc label namespace bookinfo istio.io/use-waypoint-namespace=default
+----
+
+.. Add the `istio.io/use-waypoint` label to specify the waypoint to use by running the following command:
++
+[source,terminal]
+----
+$ oc label namespace bookinfo istio.io/use-waypoint=waypoint-default
+----