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 the Kubernetes Gateway API.

The Istio classic traffic management APIs (virtual service, destination rules etc) remain at Alpha when used with the ambient data plane mode.

Mixing Istio classic API and Gateway API configuration is not supported, and will lead to undefined behavior.

Route and policy attachment

The 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:

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