Configure the effective range of Waypoint - Alibaba Cloud Service Mesh

Waypoint is an optional Layer 7 (L7) proxy in Ambient mode. If your application requires L7 features, you can configure labels to specify that traffic sent to the application is first forwarded to the corresponding Waypoint. After you deploy a Waypoint, no traffic passes through it by default. You must label a namespace or Service to direct its traffic through the Waypoint.

Important

Before you deploy a Waypoint, determine whether your application requires L7 capabilities. For details, see Description of Layer 4 and Layer 7 capabilities in Ambient mode.

Prerequisites

The Gateway API component v1.2.1 or later is installed in the cluster.

Deploy a Waypoint proxy

Create a file named waypoint.yaml with the following content:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: waypoint
  namespace: default
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - allowedRoutes:
      namespaces:
        from: Same
    name: mesh
    port: 15008
    protocol: HBONE

Field	Description
`gatewayClassName`	Set to `istio-waypoint` to create a Waypoint proxy.
`listeners[].port`	The HBONE tunnel port. Set to `15008`.
`listeners[].protocol`	Set to `HBONE`.
`allowedRoutes.namespaces.from`	Controls which namespaces can route traffic through this Waypoint. `Same` restricts it to the Waypoint's own namespace.

Apply the manifest:
```
kubectl apply -f waypoint.yaml
```

You can deploy multiple Waypoints in a cluster to assign different Waypoints to different Services. Waypoints can also be used across namespaces.

Route traffic through a Waypoint

Add the label istio.io/use-waypoint to a namespace or Service to direct its traffic through a specific Waypoint.

Note

ASM currently supports Waypoint configuration at the namespace and Service levels.

Namespace level

Label a namespace to route all Service traffic in that namespace through a Waypoint:

kubectl label namespace default istio.io/use-waypoint=waypoint

This applies the Waypoint named waypoint to every Service in the default namespace. For a complete example, see Configure Layer 7 authorization policies.

Service level

Label a specific Service to route only that Service's traffic through a Waypoint:

kubectl label service reviews istio.io/use-waypoint=reviews-svc-waypoint

This directs traffic destined for the reviews Service through the Waypoint named reviews-svc-waypoint, without affecting other Services in the same namespace.

Use Service-level configuration when different Services require different L7 policies, or when only certain Services need L7 processing.

Verify that traffic passes through the Waypoint

A Waypoint outputs access logs by default. Check its logs to confirm that traffic is being routed through it.

kubectl logs deployments/waypoint | tail -1

The output is a single-line JSON log entry. The following example is formatted for readability:

{
  "method": "GET",
  "path": "/reviews/0",
  "protocol": "HTTP/1.1",
  "response_code": "200",
  "upstream_cluster": "inbound-vip|9080|http|reviews-v1.default.svc.cluster.local;",
  "upstream_host": "envoy://connect_originate/10.0.109.98:9080",
  "start_time": "2025-06-16T08:58:43.339Z",
  "duration": "1"
}

Key fields to check:

Field	What it tells you
`response_code`	Whether the upstream Service responded successfully.
`upstream_cluster`	The target Service and version the traffic was routed to.
`path`	The HTTP path of the request.
`method`	The HTTP method (GET, POST, etc.).

If the log contains entries with valid upstream_cluster values, traffic is passing through the Waypoint.

For the complete getting started example, see Configure an authorization policy for an application.