Configure waypoint proxies

A waypoint proxy is an optional deployment of the Envoy-based proxy to add Layer 7 (L7) processing to a defined set of workloads.

Waypoint proxies are installed, upgraded and scaled independently from applications; an application owner should be unaware of their existence. Compared to the sidecar data plane mode, which runs an instance of the Envoy proxy alongside each workload, the number of proxies required can be substantially reduced.

A waypoint, or set of waypoints, can be shared between applications with a similar security boundary. This might be all the instances of a particular workload, or all the workloads in a namespace.

As opposed to sidecar mode, in ambient mode policies are enforced by the destination waypoint. In many ways, the waypoint acts as a gateway to a resource (a namespace, service or pod). Istio enforces that all traffic coming into the resource goes through the waypoint, which then enforces all policies for that resource.

Do you need a waypoint proxy?

The layered approach of ambient allows users to adopt Istio in a more incremental fashion, smoothly transitioning from no mesh, to the secure L4 overlay, to full L7 processing.

Most of the features of ambient mode are provided by the ztunnel node proxy. Ztunnel is scoped to only process traffic at Layer 4 (L4), so that it can safely operate as a shared component.

When you configure redirection to a waypoint, traffic will be forwarded by ztunnel to that waypoint. If your applications require any of the following L7 mesh functions, you will need to use a waypoint proxy:

• Traffic management: HTTP routing & load balancing, circuit breaking, rate limiting, fault injection, retries, timeouts
• Security: Rich authorization policies based on L7 primitives such as request type or HTTP header
• Observability: HTTP metrics, access logging, tracing

Deploy a waypoint proxy

Waypoint proxies are deployed declaratively using Kubernetes Gateway resources. You can use istioctl experimental subcommands to generate, apply or list these resources.

After the waypoint is deployed, the entire namespace (or whichever services or pods you choose) must be enrolled to use it.

Before you deploy a waypoint proxy for a specific namespace, confirm the namespace is labeled with istio.io/dataplane-mode: ambient:

$ kubectl get ns -L istio.io/dataplane-mode
NAME              STATUS   AGE   DATAPLANE-MODE
istio-system      Active   24h
default           Active   24h   ambient

istioctl can generate a Kubernetes Gateway resource for a waypoint proxy. For example, to generate a waypoint proxy named waypoint for the default namespace that can process traffic for services in the namespace:

$ istioctl experimental waypoint generate --for service -n default
kind: Gateway
metadata:
  labels:
    istio.io/waypoint-for: service
  name: waypoint
  namespace: default
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE

Note the Gateway resource has the istio-waypoint label set to gatewayClassName which indicates it is a waypoint provided by Istio. The Gateway resource is labeled with istio.io/waypoint-for: service, indicating the waypoint can process traffic for services, which is the default.

To deploy a waypoint proxy directly, use apply instead of generate:

$ istioctl experimental waypoint apply -n default
waypoint default/namespace applied

Or, you can deploy the generated Gateway resource:

$ kubectl apply -f - <<EOF
kind: Gateway
metadata:
  labels:
    istio.io/waypoint-for: service
  name: waypoint
  namespace: default
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
EOF

After the Gateway resource is applied, Istiod will monitor the resource, deploy and manage the corresponding waypoint deployment and service for users automatically.

Waypoint traffic types

By default, a waypoint will only handle traffic destined for services in its namespaces. This choice was made because traffic directed at a pod alone is rare, and often used for internal purposes such as Prometheus scraping, and the extra overhead of L7 processing may not be desired.

It is also possible for the waypoint to handle all traffic, only handle traffic sent directly to workloads (pods or VMs) in the cluster, or no traffic at all. The types of traffic that will be redirected to the waypoint are determined by the istio.io/waypoint-for label on the Gateway object.

The --for parameter to istioctl experimental waypoint apply can be used to change the traffic type redirected to the waypoint:

Use a waypoint proxy

When a waypoint proxy is deployed, it is not used by any resources until you explicitly configure those resources to use it.

To enable a namespace, service or Pod to use a waypoint, add the istio.io/use-waypoint label with a value of the waypoint name.

Most users will want to apply a waypoint to an entire namespace, and we recommend you start with this approach.

If you use istioctl to deploy your namespace waypoint, you can use the --enroll-namespace parameter to automatically label a namespace:

$ istioctl experimental waypoint apply -n default --enroll-namespace
waypoint default/waypoint applied
namespace default labeled with "istio.io/use-waypoint: waypoint"

Alternatively, you may add the istio.io/use-waypoint: waypoint label to the default namespace using kubectl:

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

After a namespace is enrolled to use a waypoint, any requests from any pods using the ambient data plane mode, to any service running in that namespace, will be routed through the waypoint for L7 processing and policy enforcement.

If you prefer more granularity than using a waypoint for an entire namespace, you can enroll only a specific service or pod to use a waypoint. This may be useful if you only need L7 features for some services in a namespace, if you only want an extension like a WasmPlugin to apply to a specific service, or if you are calling a Kubernetes headless service by its pod IP address.

If the istio.io/use-waypoint label exists on both a namespace and a service, the service waypoint takes precedence over the namespace waypoint as long as the service waypoint can handle service or all traffic. Similarly, a label on a pod will take precedence over a namespace label.

Configure a service to use a specific waypoint

Using the services from the sample bookinfo application, we can deploy a waypoint called reviews-svc-waypoint for the reviews service:

$ istioctl experimental waypoint apply -n default --name reviews-svc-waypoint
waypoint default/reviews-svc-waypoint applied

Label the reviews service to use the reviews-svc-waypoint waypoint:

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

Any requests from pods in the mesh to the reviews service will now be routed through the reviews-svc-waypoint waypoint.

Configure a pod to use a specific waypoint

Deploy a waypoint called reviews-v2-pod-waypoint for the reviews-v2 pod.

Recall the default for waypoints is to target services; as we explicitly want to target a pod, we need to use the istio.io/waypoint-for: workload label, which we can generate by using the --for workload parameter to istioctl.

$ istioctl experimental waypoint apply -n default --name reviews-v2-pod-waypoint --for workload
waypoint default/reviews-v2-pod-waypoint applied

Label the reviews-v2 pod to use the reviews-v2-pod-waypoint waypoint:

$ kubectl label pod -l version=v2,app=reviews istio.io/use-waypoint=reviews-v2-pod-waypoint
pod/reviews-v2-5b667bcbf8-spnnh labeled

Any requests from pods in the ambient mesh to the reviews-v2 pod IP will now be routed through the reviews-v2-pod-waypoint waypoint for L7 processing and policy enforcement.