About routing in an ambient mesh

Routing components

In-mesh routing is facilitated by ztunnels, waypoint proxies, east-west gateways (in multicluster setups), and optionally ingress and egress gateways. For more information, see the ambient component overview.

Ztunnels

Ambient mesh was intentionally designed in a layered approach to help you more easily migrate in stages to a full ambient mesh.

The easiest way to add services to your ambient mesh is by labeling the service’s namespace. The label instructs the ztunnel instance that is co-located on the same node to configure a ztunnel socket on the app pod. The socket secures traffic to and from the app via mutual TLS. Ztunnels are scoped to only process traffic on L4. That way, it can safely operate as a shared component while you try out an ambient mesh.

Waypoint proxies

After you add your apps to the ambient mesh to set up in-mesh routing via ztunnels, you can decide whether you need waypoint proxies for policy application on L7. Deploying waypoint proxies might be the second step you take to shift your policy-driven routing decisions to the ambient mesh configuration.

If your app requires any of the following L7 policies and routing capabilities, you must deploy a waypoint proxy for your app.

  • Traffic management: HTTP routing, HTTP 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

East-west gateways

In a multicluster ambient mesh, you deploy an east-west gateway to each cluster in the mesh. The east-west gateway facilitates traffic routing across clusters in the mesh. For example, if your target app is in a different cluster network than the ingress gateway or the source in-mesh app, the request is first routed to the east-west gateway that is located on the target cluster. Then, the east-west gateway forwards the request to the target app’s ztunnel socket.

For this reason, it is not recommened to apply any kind of routing logic or policies to east-west gateways. After you create the east-west gateways in a multicluster ambient mesh, you can forget about them.

Ingress and egress gateways (optional)

For other routing configurations, such as managing traffic requests either from clients outside the ambient mesh or to services outside the ambient mesh, you might configure ingress or egress gateways. In a typical ambient mesh setup, the ingress or egress gateway determines basic routing rules, such as backend destination selection, but can also apply additional policies to the traffic entering and leaving the mesh. However, keep in mind that these gateway components are not required to configure routing within the ambient mesh.

Traffic request flow

Single-cluster setups

In a single cluster setup, a traffic request to your app from a client outside of the mesh is first received through your ingress gateway. The ingress gateway routes the request to the ztunnel socket of the target app pod. The socket is configured by the ztunnel instance that is located on the same node as the app pod. It secures the traffic request before traffic is forwarded within the ambient mesh. If the target app has Layer 7 (L7) policies that are applied by a waypoint proxy, the ingress gateway sends the request first to the waypoint, which enforces the L7 policy and collects L7 metrics before forwarding the request to the app’s ztunnel socket.

Figure: Traffic flow through a single-cluster ambient mesh.
Figure: Traffic flow through a single-cluster ambient mesh.

Multicluster setups

In a multicluster setup, a traffic request to your app from a client outside of the multicluster mesh is first received through your ingress gateway.

  • If the target app is in the same cluster network as the ingress gateway, the ingress gateway routes the request to the ztunnel socket of the app pod.
  • If the target app is in a different cluster network than the ingress gateway, the ingress gateway first routes the request to the east-west gateway that is located on the target cluster. Then, the east-west gateway forwards the request to the target app’s ztunnel socket. Traffic between gateways and ztunnel sockets is secured via mTLS by default.

If the target app has Layer 7 policies that are applied by a waypoint proxy, the ingress or east-west gateway sends the request first to the waypoint, which enforces the L7 policy and collects L7 metrics before forwarding the request to the app’s ztunnel socket.

Figure: Traffic flow through a multicluster ambient mesh.
Figure: Traffic flow through a multicluster ambient mesh.

Using ingress gateways in combination with waypoints

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.

Set up in-mesh routing

Set up in-mesh routing in your ambient mesh in the following ways.

Ztunnels: You initially create ztunnels when you follow the steps to use the Gloo Operator or Helm to set up an ambient mesh. Then, to enable in-mesh routing, simply label your service namespaces to be included in the ambient mesh. The label instructs the ztunnel instance that is co-located on the same node to configure a ztunnel socket on the app pod. To get started, see the sample apps guide.

East-west gateways (multicluster only): In a multicluster environment, start by following the steps to use the Gloo Operator or Helm to create a multicluster ambient mesh. These steps involve peering the cluster networks, and deploying the east-west gateway to each cluster.

Apply Layer 7 policies

About waypoints

When you are ready to begin applying L7 policies, the recommended approach is to deploy a waypoint proxy for a service namespace and enroll the whole namespace to use that waypoint by applying the istio.io/use-waypoint=waypoint namespace label. After you enroll a namespace to use a waypoint, any requests from any pods in the ambient mesh to any service that runs in that namespace is routed through the waypoint proxy for L7 processing and policy enforcement.

For more granular control, you can add a waypoint proxy to a particular service or pod. This can be useful if you only need L7 features for some services in a namespace, but is more cumbersome to manage.

If you have multiple instances of the same app across a multicluster ambient mesh, be sure to deploy a waypoint to the namespace in each cluster that the service instances exist in.

To set up waypoint proxies, you can use Gloo Gateway, or use community ambient mesh directly.

Gloo Gateway as a waypoint proxy (recommended)

Use Gloo Gateway as the waypoint proxy for apps in your ambient mesh. Gloo Gateway is fully conformant with the Kubernetes Gateway API and extends its functionality with Solo’s custom Gateway APIs, such as RouteOption, VirtualHostOption, Upstreams, RateLimitConfig, or AuthConfig. These resources help to centrally configure routing, security, and resiliency rules for a specific component, such as a host, route, or gateway listener.

To get started, follow the Gloo Gateway as a waypoint proxy guide in the Gloo Gateway docs. This guide includes steps to use Gloo Gateway to create waypoint proxies with the gloo-waypoint Gateway class, and apply example L7 policies to the waypoint.

Community ambient mesh

To use the Gateway class provided by community ambient mesh to create waypoint proxies, istio-waypoint, see Deploy a waypoint proxy in the community ambient mesh docs.

For an example of applying an authorization policy at L7, see Authorization policy with waypoint proxies in the community ambient mesh docs.

Other mesh routing scenarios

Ingress gateways: To set up basic L4 routing to your apps, you can choose an ingress gateway from the available options in the Expose apps with an ingress gateway guide.

Egress gateways: To allow apps in your mesh to send traffic requests to an external service, follow the steps in Control traffic with an egress gateway. Note that the egress gateway is created as a waypoint proxy for an external service.