Use agentgateway

agentgateway is a data plane proxy that can be used as an alternative to Envoy. It is purpose-built for AI agent and Model Context Protocol (MCP) traffic, while also supporting general-purpose Layer 7 routing. When agentgateway is enabled, Istio can program it in place of Envoy for two roles in an ambient mesh:

• as an ingress gateway, handling north-south traffic entering the mesh, and
• as a waypoint proxy, handling east-west Layer 7 processing for a set of workloads.

This guide explains how the integration works, which APIs are supported, and how to install Istio and configure agentgateway for each role.

How the integration works

Istiod configures agentgateway exclusively through Kubernetes Gateway API resources, which it delivers to the proxy over xDS. The proxy is a distinct data plane implementation from Envoy: when a Gateway selects an agentgateway GatewayClass, Istiod provisions and manages an agentgateway Deployment and Service for it, in the same way it manages Istio’s Envoy-based gateways.

Enabling agentgateway registers two GatewayClass resources:

Because the data plane is selected per-Gateway through the gatewayClassName field, agentgateway and Istio’s default Envoy-based gateways and waypoints can coexist in the same cluster. You choose agentgateway for a specific gateway or waypoint simply by referencing one of the classes above.

Supported and unsupported configuration

Istio supports the following Gateway API resources for agentgateway:

• Gateway (using the istio-agentgateway or istio-agentgateway-waypoint class)
• HTTPRoute, GRPCRoute, TCPRoute, and TLSRoute
• InferencePool, from the Gateway API Inference Extension, for routing to AI inference workloads

Before you begin

Note that the Kubernetes Gateway API CRDs do not come installed by default on most Kubernetes clusters, so make sure they are installed before using the Gateway API:

$ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
  kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/experimental-install.yaml

Install Istio with agentgateway enabled

agentgateway support is gated behind the PILOT_ENABLE_AGENTGATEWAY feature flag on istiod, and is disabled by default. Install Istio using the ambient profile with the flag enabled. The ambient profile is required so that the waypoint GatewayClass is also registered:

$ istioctl install --set profile=ambient --set values.pilot.env.PILOT_ENABLE_AGENTGATEWAY=true -y

Confirm that both agentgateway GatewayClass resources are registered:

$ kubectl get gatewayclass istio-agentgateway istio-agentgateway-waypoint
NAME                          CONTROLLER                                  ACCEPTED   AGE
istio-agentgateway            istio.io/agentgateway-controller            True       30s
istio-agentgateway-waypoint   istio.io/agentgateway-waypoint-controller   True       30s

Deploy a sample application

Deploy the Bookinfo sample application, which is used by the examples in this guide:

$ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo.yaml@

Configure agentgateway as an ingress gateway

To use agentgateway as an ingress gateway, create a Gateway that references the istio-agentgateway class. Istiod provisions and manages the corresponding agentgateway deployment automatically.

$ kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: bookinfo-gateway
  annotations:
    networking.istio.io/service-type: ClusterIP
spec:
  gatewayClassName: istio-agentgateway
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Same
EOF

The gatewayClassName: istio-agentgateway field is what selects the agentgateway data plane instead of Envoy. By default, Istio creates a LoadBalancer service for a gateway; the networking.istio.io/service-type: ClusterIP annotation requests a ClusterIP service instead so that the gateway can be reached with kubectl port-forward in this guide.

Attach an HTTPRoute to expose the productpage service through the gateway:

$ kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: bookinfo
spec:
  parentRefs:
  - name: bookinfo-gateway
  rules:
  - matches:
    - path:
        type: Exact
        value: /productpage
    - path:
        type: PathPrefix
        value: /static
    - path:
        type: Exact
        value: /login
    - path:
        type: PathPrefix
        value: /api/v1/products
    backendRefs:
    - name: productpage
      port: 9080
EOF

Confirm that the gateway has been provisioned and is programmed. The CLASS column shows the agentgateway class:

$ kubectl get gateway bookinfo-gateway
NAME               CLASS                ADDRESS                                      PROGRAMMED   AGE
bookinfo-gateway   istio-agentgateway   bookinfo-gateway.default.svc.cluster.local   True         30s

You can now access the application through the agentgateway ingress gateway. Forward a local port to the gateway service and open http://localhost:8080/productpage in your browser:

$ kubectl port-forward svc/bookinfo-gateway 8080:80

Configure agentgateway as a waypoint

A waypoint proxy adds Layer 7 processing to a set of workloads in an ambient mesh. To use agentgateway for this role, deploy a Gateway that references the istio-agentgateway-waypoint class.

First, confirm the namespace is enrolled in the ambient data plane:

$ kubectl label namespace default istio.io/dataplane-mode=ambient
namespace/default labeled

Deploy the waypoint. Like all waypoints, it must define a single listener named mesh on port 15008 using the HBONE protocol; the only difference from an Envoy waypoint is the gatewayClassName:

$ kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: agentgateway-waypoint
  labels:
    istio.io/waypoint-for: service
spec:
  gatewayClassName: istio-agentgateway-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
EOF

Confirm the waypoint is programmed:

$ kubectl get gateway agentgateway-waypoint
NAME                    CLASS                         ADDRESS        PROGRAMMED   AGE
agentgateway-waypoint   istio-agentgateway-waypoint   10.96.15.112   True         30s

Enroll a service to use the waypoint by adding the istio.io/use-waypoint label with the name of the waypoint. For example, to send traffic destined for the reviews service through the agentgateway waypoint:

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

Requests from workloads in the ambient mesh to the reviews service are now routed through the agentgateway waypoint for Layer 7 processing. To learn more about enrolling namespaces, services, and pods, and about how waypoints handle different traffic types, see Configure waypoint proxies.

To apply Layer 7 routing policy at the waypoint, attach a Gateway API route to the Service using a parentRef whose kind is Service. For example, the following HTTPRoute sends 90% of traffic for the reviews service to reviews-v1 and 10% to reviews-v2:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: reviews
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

Cleanup

Remove the ingress gateway and its route:

$ kubectl delete httproute bookinfo
$ kubectl delete gateway bookinfo-gateway

Remove the waypoint and un-enroll the reviews service:

$ kubectl label service reviews istio.io/use-waypoint-
$ kubectl delete gateway agentgateway-waypoint

Remove the sample application and the ambient label:

$ kubectl delete -f @samples/bookinfo/platform/kube/bookinfo.yaml@
$ kubectl label namespace default istio.io/dataplane-mode-

Uninstall Istio:

$ istioctl uninstall --purge -y
$ kubectl delete namespace istio-system

Remove the Kubernetes Gateway API CRDs:

$ kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/experimental-install.yaml