Use Layer 7 features

By adding a waypoint proxy to your traffic flow you can enable more of Istio’s features. Waypoints are configured using Gateway API.

Route and policy attachment

Gateway API defines the relationship between objects (such as routes and gateways) in terms of attachment.

• Route objects (such as HTTPRoute) include a way to reference the parent resources it wants to attach to.
• Policy objects are considered metaresources: objects that augments the behavior of a target object in a standard way.

The tables below show the type of attachment that is configured for each object.

Traffic routing

With a waypoint proxy deployed, you can use the following traffic route types:

(TLS and TCP routing are stable features in Istio, but support for these objects remains at Alpha because the Gateway API objects are still in the experimental channel.)

Refer to the traffic management documentation to see the range of features that can be implemented using these routes.

Security

Without a waypoint installed, you can only use Layer 4 security policies. By adding a waypoint, you gain access to the following policies:

Considerations for authorization policies

In ambient mode, authorization policies can either be targeted (for ztunnel enforcement) or attached (for waypoint enforcement). For an authorization policy to be attached to a waypoint it must have a targetRef which refers to the waypoint, or a Service which uses that waypoint.

The ztunnel cannot enforce L7 policies. If a policy with rules matching L7 attributes is targeted with a workload selector (rather than attached with a targetRef), such that it is enforced by a ztunnel, it will fail safe by becoming a DENY policy.

See the L4 policy guide for more information, including when to attach policies to waypoints for TCP-only use cases.

Observability

The full set of Istio traffic metrics are exported by a waypoint proxy.

Extension

As the waypoint proxy is a deployment of Envoy, some of the extension mechanisms that are available for Envoy in sidecar mode are also available to waypoint proxies.

† Read more on how to extend waypoints with WebAssembly plugins.

Extension configurations are considered policy by the Gateway API definition.

Scoping routes or policies

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 a policy to the entire waypoint — so that it applies to all traffic enrolled to use it — set Gateway as the parentRefs or targetRefs value, depending on the type.

To scope an AuthorizationPolicy policy to apply to the waypoint named default for 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 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

Unsupported APIs with waypoints

Some Istio APIs are deliberately not supported by waypoints in ambient mode. These APIs can still be used with classic Istio Gateways in an ambient mesh.

VirtualService

Istio’s classic traffic routing API is not supported for configuring waypoint traffic routing, though it works in some circumstances.

Any use of VirtualService with waypoints is considered Alpha, and may be subject to change in future releases. Istio’s maintainers do not intend to remove this support, but will not be progressing it to any further feature phase.

Migrating from VirtualService to Gateway API routes

Only a single VirtualService can be used for mesh traffic matching a certain hostname. However, multiple Gateway API routes can refer to the same host.

This is especially relevant when you are migrating from VirtualService to Gateway API routes. If you create one or more HTTPRoutes which specify a Service that is also in use with a VirtualService, the HTTPRoute/s will apply and the VirtualService will not.

To avoid this situation, users migrating from sidecars should look to convert their VirtualService configuration to Gateway API routes. The ingress2gateway project has limited support for this use case. Caution is advised, especially for users who use subset routing

Using features that are not in Gateway API

A small number of Istio’s features cannot currently be expressed in Gateway API: for example, fault injection and direct response. It is technically possible to use VirtualService for these use cases, as long as the configured hosts do not conflict with the parentRefs of any Gateway API route as mentioned above.

DestinationRule subsets

Gateway API has no ability to address subsets. Instead, you must define additional Services which have a more granular selector than the original.

The other features of DestinationRule are supported.

Classic Istio Gateways

Classic Istio Gateways can be used to route traffic into an ambient mesh. These can still be configured with VirtualService (i.e. where the gateways field refers to a named ingress gateway), alongside waypoints which are configured with Gateway API routes.

EnvoyFilter

EnvoyFilter is Istio’s break-glass API for advanced configuration of Envoy proxies. Please note that EnvoyFilter is not currently supported for any existing Istio version with waypoint proxies. While it may be possible to use EnvoyFilter with waypoints in limited scenarios, its use is not supported, and is actively discouraged by the maintainers. The alpha API may break in future releases as it evolves. We expect official support will be provided at a later date.