Configure waypoint proxies

A waypoint proxy is an optional deployment of an Envoy-based proxy that adds 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. Unlike in a sidecar-based service mesh architecture where an instance of the Envoy proxy runs alongside each workload, the number of required proxies for L7 processing is substantially reduced in ambient mesh.

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.

Layer 7 policies are enforced by the waypoint that is associated with the target destination. Because of that, the waypoint acts as a gateway for resources in a cluster, such as a namespace, service or pod.

Is a waypoint required?

The layered approach of ambient mesh allows users to adopt Istio in a more incremental fashion so that you can smoothly transition from having no mesh, to the secure overlay layer provided by ztunnel, to full L7 processing.

The ztunnel is scoped to only process traffic at Layer 4 (L4), so that it can safely operate as a shared component. However, if your app requires any of the following L7 policies and L7 routing capabilities, you must deploy a waypoint proxy:

• 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, tracing

Deploy a waypoint proxy

Waypoint proxies are deployed using the Kubernetes Gateway API. To make it easier to create a waypoint configuration, and apply it to your resources, you can use istioctl waypoint subcommands.

$ kubectl get ns -L istio.io/dataplane-mode

NAME              STATUS   AGE   DATAPLANE-MODE
istio-system      Active   24h
default           Active   24h   ambient

istioctl waypoint generate --for all -n default

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  labels:
    istio.io/waypoint-for: all
  name: waypoint
  namespace: default
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE

$ istioctl waypoint apply -n default --enroll-namespace

waypoint default/waypoint applied

Congratulations! You successfully deployed a waypoint proxy for the apps in the default namespace. The Istio control plane automatically monitors the Gateway resource, and deploys and manages the waypoint proxy deployment and service for you.

Waypoint label usage

To enforce policies with a waypoint, it is critical to understand how the istio.io/waypoint-for and istio.io/use-waypoint labels affect traffic routing.

Waypoint selection occurs based on the destination type, service or workload, to which traffic was originally addressed. The Gateway resource that represents the waypoint must have the corresponding istio.io/waypoint-for label to be considered a valid waypoint for this type of traffic. However, only when the target resource that traffic is addressed to also has the istio.io/use-waypoint label and represents the type of traffic that the waypoint can serve, traffic is actually routed through the waypoint.

For example, if traffic is addressed to a service, but the target service does not have the istio.io/use-waypoint label, traffic is not sent through the waypoint, even if the workload that backs the service does have an attached waypoint.

Review the following table to understand traffic implications when using these labels:

Considerations for waypoints

Review considerations for combining an Istio or 3rd-party ingress gateway with waypoint proxies.

Istio ingress gateway

When an in-mesh app sends a request to another in-mesh app that has a waypoint configured, the traffic request is routed from the source app’s ztunnel socket, to the waypoint proxy so that L7 policies can be applied. Then, the request is forwarded from the waypoint proxy to the backend app’s ztunnel socket for further processing. This traffic flow ensures that requests are captured by the corresponding ztunnel instances and are correctly routed to the backend app.

Istio ingress gateways on the other hand implement the HBONE protocol and therefore do not need to rely on ztunnels to capture ambient mesh traffic or use its routing capabilities. Instead, the ingress gateway sends incoming traffic to a backend workload directly. This default behavior bypasses the waypoint. Although it is more efficient to route traffic to the backend workload directly, you might still want traffic from the ingress gateway to route through the waypoint. For example, you might want routing logic to be configured on the ingress gateway and security, resiliency, and other policies to be enforced on the waypoint.

To configure the Istio ingress gateway to route traffic to a waypoint instead of the backend, you add the istio.io/ingress-use-waypoint=true label to the Gateway resource that represents the ingress gateway. This label allows you to apply different L7 policies on the ingress gateway and waypoints. The following rules might help you decide what policies to apply to which layer:

• 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.

Note that your waypoints and target services or workloads must also have the appropriate label for ingress traffic to be correctly routed through the waypoint. Therefore, you set the following three labels in your environment:

• Set istio.io/ingress-use-waypoint=true on the Gateway resource that represents the Istio ingress gateway.
• Set the appropriate istio.io/waypoint-for label on the Gateway resource that represents the waypoint proxy. For more information, see Waypoint label usage.
• Set the appropriate istio.io/use-waypoint label on the target namespace, service, or workload. For more information, see Waypoint label usage.

3rd-party ingress gateways

You can integrate with 3rd-party ingress solutions, such as kgateway, and configure them as an ingress gateway to your ambient mesh. Unlike Istio ingress gateways, most 3rd-party gateway solutions do not implement the HBONE protocol and therefore must rely on ztunnel to capture traffic and route requests. Because of that, traffic is routed through a waypoint before it is forwarded to the backend app, even if the ingress gateway does not have the istio.io/ingress-use-waypoint=true label. However, 3rd-party ingress gateways typically do not send traffic to a service in the mesh. Instead, these gateways route traffic directly to pods in order to implement more advanced load balancing. This type of traffic is considered to-workload traffic. In-mesh services on the other hand send traffic to a service instead of the pod directly.

To ensure that your waypoint is not bypassed depending on the type of traffic that is sent, consider creating the waypoint with the istio.io/waypoint-for: all label. This label ensures that the waypoint can handle both workload and service traffic. In addition, consider adding the istio.io/use-waypoint label to the target namespace so that all workloads and services in that namespace can use the waypoint. If you do not want or cannot label the entire namespace, and instead want to use different waypoints for specific services and workloads, keep the following rules in mind:

• If your ingress gateway produces workload traffic, you must add the istio.io/use-waypoint label to the target workload. Evaluate if other services in the mesh send traffic to the target’s service. If so, also add the istio.io/use-waypoint label to the corresponding target service.
• If your ingress gateway sends traffic to a service, you must add the istio.io/use-waypoint label to the target service.

To summarize, for ingress traffic from 3rd-party ingress gateways to be routed throught the waypoint, you set the following labels:

• Set the appropriate istio.io/waypoint-for label on the Gateway resource that represents the waypoint proxy. You can use the istio.io/waypoint-for: all label to allow the waypoint to handle both service and workload traffic. For more information, see Waypoint label usage.
• Set the appropriate istio.io/use-waypoint label on the target namespace, service, or workload. For more information, see Waypoint label usage.

Enroll namespaces or services to use waypoints

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 the waypoint name.

Configure a namespace to use a waypoint

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

$ istioctl waypoint apply -n default --enroll-namespace

Alternatively, you can add the label to the namespace directly:

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

After a namespace is enrolled 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.

Want to have more granular control over the resources that use the waypoint? With ambient mesh, 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, 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.

Configure a service to use a specific waypoint

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

$ istioctl waypoint apply -n default --name reviews-svc-waypoint

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

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

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

Keep in mind that the default destination type for waypoints are services. Because we want to target a specific pod, we need to use the istio.io/waypoint-for: workload label on the waypoint proxy. You can automatically generate this label by using the --for workload option when applying your waypoint.

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

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

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

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.

Attach policies and routes

A route or policy can be scoped to apply to all traffic traversing a waypoint proxy, or only specific services.

Attach to the entire waypoint proxy

To attach a route or policy to a waypoint so that it is applied to all traffic that passes through the waypoint, use kind: Gateway and the name of the waypoint in the spec.parentRefs (route) or spec.targetRefs (policy) field. The following AuthorizationPolicy applies to a waypoint proxy named default in the default namespace.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: view-only
  namespace: default
spec:
  targetRefs:
  - kind: Gateway
    group: gateway.networking.k8s.io
    name: default
  action: ALLOW
  rules:
  - from:
    - source:
        namespaces: ["default", "istio-system"]
    to:
    - operation:
        methods: ["GET"]

Attach to a specific service

You can also attach a route to one or more specific services within the waypoint. Set a kind: Service as the parentRefs or targetRefs value, as appropriate.

To apply the reviews HTTPRoute to the reviews service in the default namespace:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: reviews
  namespace: default
spec:
  parentRefs:
  - group: ""
    kind: Service
    name: reviews
    port: 9080
  rules:
  - backendRefs:
    - name: reviews-v1
      port: 9080
      weight: 90
    - name: reviews-v2
      port: 9080
      weight: 10

Scale waypoints

Because waypoints run independently of the workloads that use them, they can be scaled like any Kubernetes resource.

The Horizontal Pod Autoscaler can be attached to the Deployment that backs the Gateway object, which will have the same name.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: waypoint-hpa
spec:
  # Match the generated Deployment by reference
  # Note: Do not use `kind: Gateway`.
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: waypoint
  minReplicas: 2
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50

You can also apply a Pod Disruption Budget for higher availability of your waypoint. As this is selected with a label selector, use the gateway-name waypoint, which is set to the name of the waypoint.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: waypoint-pdb
spec:
  minAvailable: 1
  selector:
    # Match the generated Deployment for "waypoint" by label
    matchLabels:
      gateway.networking.k8s.io/gateway-name: waypoint

Use waypoints from other namespaces

By default, a waypoint proxy can be used by resources within the same namespace. However, it is possible to use waypoints from other namespaces.

Configure a waypoint for cross-namespace use

In order to enable cross-namespace use of a waypoint, the Gateway must be configured to allow routes from other namespaces.

The following Gateway resource allows routes from a namespace called cross-namespace-waypoint-consumer to use the egress-gateway.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: egress-gateway
  namespace: common-infrastructure
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            kubernetes.io/metadata.name: cross-namespace-waypoint-consumer

Configure resources to use a cross-namespace waypoint proxy

By default, the Istio control plane looks for a waypoint in the same namespace as the resource that is configured to use a waypoint. To do that, the control plane looks extracts the waypoint proxy name from the istio.io/use-waypoint label that is applied to the resource.

To instruct the control plane to look for a waypoint in a different namespace, you must apply the istio.io/use-waypoint and istio.io/use-waypoint-namespace labels to your resource. Together, these two labels specify the name and namespace of your waypoint.

For example, to configure a ServiceEntry named istio-site to use a waypoint named egress-gateway in the namespace named common-infrastructure, you could use the following commands:

$ kubectl label serviceentry istio-site istio.io/use-waypoint=egress-gateway
$ kubectl label serviceentry istio-site istio.io/use-waypoint-namespace=common-infrastructure

Remove waypoints

To remove the waypoint layer from a namespace, delete the Gateway resources and remove the enrollment label. The folling commands removes all waypoint proxies in the default namespace.

$ istioctl waypoint delete --all -n default
$ kubectl label ns default istio.io/use-waypoint-