Understanding L7 Traffic Management in Istio Ambient Mode: From Ztunnel to Waypoint Proxy
An in-depth exploration of Istio ambient mode’s L7 traffic path, covering transparent interception, policy application, and traffic forwarding from ztunnel to waypoint proxy.
Click to show the outline
In Istio’s ambient mode, ztunnel acts as a node-level security proxy responsible for L4 traffic interception and encryption between services. However, ztunnel doesn’t handle L7 tasks such as HTTP-based routing or policy enforcement. For L7 traffic management, waypoint proxy, powered by Envoy, processes HTTP requests and applies L7 policies. When ztunnel detects traffic requiring L7 processing, it forwards the traffic using the HBONE protocol to the waypoint proxy. The proxy applies policies, logs telemetry data, and forwards requests to the target Pod through ztunnel.
This post details this traffic forwarding path, breaking down how L7 traffic flows from ztunnel to waypoint proxy and ultimately to the target Pod.
Roles and Responsibilities in Ambient Mode
ztunnel (L4 Traffic Manager)
- Intercepts traffic at L4 (TCP) level.
- Secures traffic using mTLS encryption and authenticates service identities.
Waypoint Proxy (L7 Traffic Manager)
- Manages L7 traffic policies such as HTTP routing, authentication, authorization, and telemetry.
- Acts as an application-aware proxy, applying business-specific policies and sending metrics to the observability stack.
When a request requires L7 handling (e.g., productpage
service calling reviews-v1
), ztunnel forwards traffic to waypoint proxy using HBONE, enabling transparent policy application and telemetry collection.
L7 Traffic Path in Ambient Mode
The following diagram illustrates the L7 traffic path in Istio ambient mode:
The following two pictures respectively show the L7 traffic processing paths of the source Pod and the destination Pod in the same node and cross-node scenarios.
Traffic Path Breakdown
1. Application Request Sent
The productpage
service initiates an HTTP request to the reviews-v1
service at reviews.default.svc.cluster.local:9080
.
2. ztunnel L4 Traffic Interception
Ztunnel on the source node intercepts the outbound request from productpage
using Kubernetes’ iptables
rules. It inspects Istio’s control plane configuration and determines that L7 policies must be applied.
3. Forwarding Traffic Using HBONE Protocol
Ztunnel uses HBONE protocol instead of native Envoy-to-Envoy XDS or TCP+mTLS tunneling. HBONE (HTTP-Based Overlay Network Environment) encapsulates traffic in HTTP/2, enabling transparent forwarding of traffic for L7 processing.
ztunnel wraps the intercepted traffic into an HBONE tunnel and forwards it to waypoint proxy.
4. L7 Processing and Policy Enforcement by Waypoint Proxy
Waypoint proxy, built on Envoy, verifies the downstream client’s mTLS credentials using SPIFFE IDs and contextual metadata for authentication. It then applies the following policies:
- HTTP Routing & Load Balancing: Routes requests based on Host/Path headers.
- Authorization Policies: Validates access through headers and tokens.
- Traffic Shaping: Injects faults, rate-limits requests, and implements retries.
- Telemetry Collection: Tracks metrics, logs, traces, and request durations.
Waypoint proxy forwards the processed traffic through HBONE to the target node’s ztunnel.
5. Delivering Traffic to Target Pod
ztunnel on the target node receives traffic from waypoint proxy through HBONE, decapsulates the request, and forwards it to the target Pod (reviews-v1
) on its application port.
Insights and Key Takeaways
1. Transparent Routing via Waypoint Proxy
- Waypoint proxy only knows the target Pod’s IP address and rewritten port
15008
. - ztunnel manages traffic redirection using Kubernetes
iptables
.
2. End-to-End Security
- Mutual TLS (mTLS) with SPIFFE ID validation ensures secure traffic transmission.
- Traffic cannot bypass ztunnel, enforcing a Zero Trust Architecture.
3. Transparent Policy Enforcement
- Developers don’t need to change the application code.
- Traffic control, security, and telemetry are fully automated at the data plane level.
How to Debug Ambient Mode?
1. ztunnel Debugging
Use istioctl ztunnel
to inspect ztunnel configurations and states.
2. Waypoint Proxy Debugging
- Use Envoy-specific commands such as
istioctl pc
andistioctl ps
to inspect Envoy proxy configurations. - Use
istioctl waypoint
for streamlined configuration inspection.
Conclusion
Istio ambient mode uses ztunnel for L4 traffic processing, including transparent interception, mTLS encryption, and forwarding. L7 tasks such as HTTP-based routing, policy enforcement, and telemetry collection are managed by waypoint proxy, with communication between ztunnel and waypoint proxy facilitated by HBONE protocol.
This innovative design eliminates sidecars, simplifying operations while maintaining high performance, security, and observability.