istio.io/content/en/docs/ambient/usage/waypoint/index.md

title	description	weight	aliases	owner	test
Configure waypoint proxies	Gain the full set of Istio features with optional Layer 7 proxies.	30	/docs/ops/ambient/usage/waypoint /latest/docs/ops/ambient/usage/waypoint	istio/wg-networking-maintainers	yes

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 {{< gloss >}}data plane{{< /gloss >}} 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 {{< gloss >}}sidecar{{< /gloss >}} 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 using Kubernetes Gateway resources.

{{< boilerplate gateway-api-install-crds >}}

You can use istioctl waypoint 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:

{{< text syntax=bash snip_id=check_ns_label >}} $ kubectl get ns -L istio.io/dataplane-mode NAME STATUS AGE DATAPLANE-MODE istio-system Active 24h default Active 24h ambient {{< /text >}}

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:

{{< text syntax=bash snip_id=gen_waypoint_resource >}} $ istioctl 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 {{< /text >}}

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:

{{< text syntax=bash snip_id=apply_waypoint >}} $ istioctl waypoint apply -n default waypoint default/waypoint applied {{< /text >}}

Or, you can deploy the generated Gateway resource:

{{< text syntax=bash >}} $ 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 {{< /text >}}

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 waypoint apply can be used to change the traffic type redirected to the waypoint:

waypoint-for value	Traffic type
service	Kubernetes services
workload	Pod or VM IPs
all	Both service and workload traffic
none	No traffic (useful for testing)

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.

{{< tip >}} Most users will want to apply a waypoint to an entire namespace, and we recommend you start with this approach. {{< /tip >}}

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

{{< text syntax=bash snip_id=enroll_ns_waypoint >}} $ istioctl waypoint apply -n default --enroll-namespace waypoint default/waypoint applied namespace default labeled with "istio.io/use-waypoint: waypoint" {{< /text >}}

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

{{< text syntax=bash >}} $ kubectl label ns default istio.io/use-waypoint=waypoint namespace/default labeled {{< /text >}}

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.

{{< tip >}} 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. {{< /tip >}}

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:

{{< text syntax=bash >}} $ istioctl waypoint apply -n default --name reviews-svc-waypoint waypoint default/reviews-svc-waypoint applied {{< /text >}}

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

{{< text syntax=bash >}} $ kubectl label service reviews istio.io/use-waypoint=reviews-svc-waypoint service/reviews labeled {{< /text >}}

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.

{{< tip >}} 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. {{< /tip >}}

{{< text syntax=bash >}} $ istioctl waypoint apply -n default --name reviews-v2-pod-waypoint --for workload waypoint default/reviews-v2-pod-waypoint applied {{< /text >}}

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

{{< text syntax=bash >}} $ kubectl label pod -l version=v2,app=reviews istio.io/use-waypoint=reviews-v2-pod-waypoint pod/reviews-v2-5b667bcbf8-spnnh labeled {{< /text >}}

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.

Cleaning up

You can remove all waypoints from a namespace by doing the following:

{{< text syntax=bash snip_id=delete_waypoint >}} $ istioctl waypoint delete --all -n default $ kubectl label ns default istio.io/use-waypoint- {{< /text >}}

{{< boilerplate gateway-api-remove-crds >}}