Overview

Learn about waypoint proxies and how to apply Layer 7 policies for apps in your ambient mesh.

The community waypoint proxy is an optional Envoy-based proxy deployment that adds Layer 7 (L7) processing capabilities to workloads in your ambient mesh. Unlike sidecar architectures where each workload requires its own proxy instance, a single waypoint proxy is shared between all apps in the same service account, reducing the number of required proxies while operating within a shared security boundary.

For more information about how waypoints work alongside ztunnels and east-west gateways, see the traffic management overview.

When to use waypoints

While ztunnel handles Layer 4 (L4) processing safely as a shared component, you need to deploy a waypoint when apps require any of the following:

• Traffic management: HTTP routing, load balancing, circuit breaking, rate limiting, fault injection, retries, and timeouts
• Security: Authorization policies based on L7 primitives, such as request types or HTTP headers
• Observability: HTTP metrics, access logging, and tracing

Waypoints for egress traffic

You can also deploy a waypoint proxy as an egress gateway to apply L7 policies to traffic leaving the mesh, such as TLS origination, header manipulation, HTTP authorization, and rate limiting. Bind a ServiceEntry to the waypoint using the istio.io/use-waypoint label, the same way you bind in-mesh services. For details, see Egress with a waypoint proxy.

Ingress gateway considerations

In an ambient service mesh, both gateways and waypoint proxies can be used to route traffic, apply traffic, security, and resiliency policies, and perform authentication.

When you have a waypoint proxy for a target app, in-mesh traffic requests are always routed to the waypoint proxy for the target app first. When one in-mesh app sends a request to another in-mesh app that has a waypoint, the traffic request is sent to the waypoint proxy instead of directly to the backend app.

However, by default in Istio, ingress gateways send incoming traffic requests to backend destinations directly, even if a destination uses a waypoint. This default behavior helps prevent double handling; for example, if you created rules for traffic splitting on both the ingress gateway and a waypoint proxy, this behavior ensures that the rules are not applied twice.

This behavior requires you to add certain policies on both the gateway and the waypoint. To prevent this, you can instead enable ingress waypoint routing on a service by labeling it with istio.io/ingress-use-waypoint=true. This label configures the ingress gateway to send traffic requests to the configured waypoint, and not directly to the destination service.

If you use this service label for your waypoint-enabled services, the following approach is recommended as the ideal architecture for a fully-functioning ambient service mesh:

• Gateways: Apply minimal routing logic, such as through HTTPRoutes, that is sufficient only for selecting a backend app. Avoid applying policies to gateways, except for policies that must be applied at the edge, such as rate limiting or user authentication.
• Waypoints: Apply all other routing and policy logic.

In a peered multicluster environment with Solo Enterprise for Istio (east-west gateway peering with auto-generated ServiceEntry and WorkloadEntry resources), you only need to set istio.io/ingress-use-waypoint on the Service or namespace in the cluster where the workload runs. The peering controller propagates it automatically to connected clusters, so ingress gateways throughout the mesh route traffic through the waypoint without additional configuration.

The label uses the following precedence order:

1. istio.io/ingress-use-waypoint label on the Kubernetes Service (highest priority). Setting the label to false explicitly disables waypoint routing even if the namespace has the label set to true.
2. istio.io/ingress-use-waypoint label on the namespace.
3. If no local Service or namespace label is set, the label is inherited from remote services. If any remote cluster has the label set to true on its service, the observing cluster treats the service as waypoint-enabled for ingress traffic.