Routes

Documentation

Agentgateway

Routes

The agentgateway data plane supports the Gateway API routing resources, including HTTPRoute, GRPCRoute, TCPRoute, and TLSRoute.

⚠️

Agentgateway supports the routing rules and policies that are native to the Kubernetes Gateway API, such as basic matching, rewrites, retries, and timeouts. Note that agentgateway does not yet support kgateway TrafficPolicies. Any guide that relies on TrafficPolicies will not work with the agentgateway data plane. Instead, use the kgateway Envoy-based data plane.

Before you begin

Follow the Get started guide to install kgateway with agentgateway enabled.

Make sure that agentgateway is enabled in kgateway.

helm get values kgateway -n kgateway-system -o yaml

Example output:


agentgateway:
  enabled: true

HTTP

Use agentgateway to proxy HTTP requests to your backend services.

Follow the Sample HTTP app instructions to create a sample HTTP app, a Gateway with an HTTP listener that uses the agentgateway GatewayClass, and an HTTPRoute.
Check out the following guides for more advanced routing use cases. Agentgateway supports the routing rules and policies that are native to the Kubernetes Gateway API, such as basic matching, rewrites, retries, and timeouts. Note that agentgateway does not yet support kgateway TrafficPolicies. Any guide that relies on TrafficPolicies will not work with the agentgateway data plane. Instead, use the kgateway Envoy-based data plane.

Routes to external services

Follow the Static backend guide to create a static backend for an external HTTP service. Then, use an HTTPRoute to route traffic to that service through your agentgateway. When you set up your Gateway, make sure to use the agentgateway GatewayClass.

gRPC

Use agentgateway to proxy gRPC requests to your backend services.

Deploy a gRPC sample echo app and a sample gRPC curl client.

kubectl apply -f- <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: grpc-echo
spec:
  selector:
    matchLabels:
      app: grpc-echo
  replicas: 1
  template:
    metadata:
      labels:
        app: grpc-echo
    spec:
      containers:
        - name: grpc-echo
          image: ghcr.io/projectcontour/yages:v0.1.0
          ports:
            - containerPort: 9000
              protocol: TCP
          env:
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: GRPC_ECHO_SERVER
              value: "true"
            - name: SERVICE_NAME
              value: grpc-echo
---
apiVersion: v1
kind: Service
metadata:
  name: grpc-echo-svc
spec:
  type: ClusterIP
  ports:
    - port: 3000
      protocol: TCP
      targetPort: 9000
      appProtocol: kubernetes.io/h2c
  selector:
    app: grpc-echo
---
apiVersion: v1
kind: Pod
metadata:
  name: grpcurl-client
spec:
  containers:
    - name: grpcurl
      image: docker.io/fullstorydev/grpcurl:v1.8.7-alpine
      command:
        - sleep
        - "infinity"
EOF

Create a Gateway that uses the agentgateway GatewayClass and an HTTP listener that can be used for gRPC.

kubectl apply -f- <<EOF
kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
  name: agentgateway
spec:
  gatewayClassName: agentgateway
  listeners:
    - protocol: HTTP
      port: 8080
      name: http
      allowedRoutes:
        namespaces:
          from: All
EOF

Create a GRPCRoute that routes traffic to the sample echo app.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-route
spec:
  parentRefs:
    - name: agentgateway
  hostnames:
    - "example.com"
  rules:
    - matches:
        - method:
            method: ServerReflectionInfo
            service: grpc.reflection.v1alpha.ServerReflection
        - method:
            method: Ping
      backendRefs:
        - name: grpc-echo-svc
          port: 3000
EOF

Get the address of the Gateway for your gRPC routes.

export INGRESS_GW_ADDRESS=$(kubectl get svc -n default agentgateway -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS

kubectl port-forward deployment/agentgateway -n default 8080:8080

Send a request to the gRPC server with the grpcurl client. If you do not have this client locally, you can log in to the gRPC client pod that you previously deployed.

grpcurl \
  -plaintext \
  -authority example.com \
  -d '{}' $INGRESS_GW_ADDRESS$:8080 yages.Echo/Ping

grpcurl \
  -plaintext \
  -authority example.com \
  -d '{}' localhost:8080 yages.Echo/Ping

Example output:

{
  "text": "pong"
}

Optional: You can remove the resources that you created in this guide.

kubectl delete Deployment grpc-echo
kubectl delete Service grpc-echo-svc
kubectl delete Pod grpcurl-client
kubectl delete Gateway agentgateway
kubectl delete GRPCRoute grpc-route

TCP

Follow the TCP listener guide to create a TCP listener and a TCPRoute.

Make sure to create the Gateway with the agentgateway GatewayClass.

Example TCP listener configuration:

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tcp-gateway
  namespace: kgateway-system
  labels:
    app: tcp-echo
spec:
  gatewayClassName: agentgateway
  listeners:
  - protocol: TCP
    port: 8000
    name: tcp
    allowedRoutes:
      kinds:
      - kind: TCPRoute
EOF

Review the following table to understand this configuration.

Setting	Description
`spec.gatewayClassName`	The name of the Kubernetes GatewayClass that you want to use to configure the Gateway. When you set up kgateway, a default GatewayClass is set up for you. To use the default Envoy-based kgateway proxy, set the `gatewayClassName` to `kgateway`. To use agentgateway, set the `gatewayClassName` to `agentgateway`.
`spec.listeners`	Configure the listeners for this Gateway. In this example, you configure a TCP Gateway that listens for incoming traffic on port 8000. The Gateway can serve TCPRoutes from any namespace.

Create a Gateway that enables the attachment of ListenerSets.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tcp-gateway
  namespace: kgateway-system
  labels:
    app: tcp-echo
spec:
  gatewayClassName: agentgateway
  allowedListeners:
    namespaces:
      from: All
  listeners:
  - protocol: TCP
    port: 80
    name: generic-tcp
    allowedRoutes:
      kinds:
      - kind: TCPRoute
EOF

Review the following table to understand this configuration.

Setting	Description
`spec.gatewayClassName`	The name of the Kubernetes GatewayClass that you want to use to configure the Gateway. When you set up kgateway, a default GatewayClass is set up for you. To use the default Envoy-based kgateway proxy, set the `gatewayClassName` to `kgateway`. To use agentgateway, set the `gatewayClassName` to `agentgateway`.
`spec.allowedListeners`	Enable the attachment of ListenerSets to this Gateway. The example allows listeners from any namespace.
`spec.listeners`	Optionally, you can configure a listener that is specific to the Gateway. Note that due to a Gateway API limitation, you must configure at least one listener on the Gateway resource, even if the listener is not used and is a generic, “dummy” listener. This generic listener cannot conflict with the listener that you configure in the ListenerSet, such as using the same port or name. In this example, the generic listener is configured on port 80, which differs from port 8000 in the ListenerSet that you create later.

Create a ListenerSet that configures a TCP listener for the Gateway.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XListenerSet
metadata:
  name: my-tcp-listenerset
  namespace: kgateway-system
  labels:
    app: tcp-echo
spec:
  parentRef:
    name: tcp-gateway
    namespace: kgateway-system
    kind: Gateway
    group: gateway.networking.k8s.io
  listeners:
  - protocol: TCP
    port: 8000
    name: tcp-listener-set
    allowedRoutes:
      kinds:
      - kind: TCPRoute
EOF

Review the following table to understand this configuration.

Setting	Description
`spec.parentRef`	The name of the Gateway to attach the ListenerSet to.
`spec.listeners`	Configure the listeners for this ListenerSet. In this example, you configure a TCP listener for port 8000. The gateway can serve TCPRoutes from any namespace.

TLS

Follow the TLS listener guide to create a TLS listener and a TLSRoute. Make sure to create the Gateway with the agentgateway GatewayClass.

Example TLS listener configuration:

Create a Gateway that passes through incoming TLS requests for the nginx.example.com domain.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tls-passthrough
  namespace: kgateway-system
spec:
  gatewayClassName: agentgateway
  listeners:
  - name: tls
    protocol: TLS
    hostname: "nginx.example.com"
    tls:
      mode: Passthrough
    port: 8443
    allowedRoutes:
      namespaces:
        from: All
EOF

Review the following table to understand this configuration.

Setting	Description
`spec.gatewayClassName`	The name of the Kubernetes GatewayClass that you want to use to configure the Gateway. When you set up kgateway, a default GatewayClass is set up for you. To use the default Envoy-based kgateway proxy, set the `gatewayClassName` to `kgateway`. To use agentgateway, set the `gatewayClassName` to `agentgateway`.
`spec.listeners`	Configure the listeners for this Gateway. In this example, you configure a TLS passthrough Gateway that listens for incoming traffic for the `nginx.example.com` domain on port 8443. The Gateway can serve TLS routes from any namespace.
`spec.listeners.tls.mode`	The TLS mode for incoming requests. In this example, TLS requests are passed through to the backend service without being terminated at the Gateway.

Create a Gateway that enables the attachment of ListenerSets.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tls-passthrough
  namespace: kgateway-system
spec:
  gatewayClassName: agentgateway
  allowedListeners:
    namespaces:
      from: All
  listeners:
  - protocol: TLS
    port: 80
    name: generic-tls
    allowedRoutes:
      namespaces:
        from: All
EOF

Review the following table to understand this configuration.

Setting	Description
`spec.gatewayClassName`	The name of the Kubernetes GatewayClass that you want to use to configure the Gateway. When you set up kgateway, a default GatewayClass is set up for you. To use the default Envoy-based kgateway proxy, set the `gatewayClassName` to `kgateway`. To use agentgateway, set the `gatewayClassName` to `agentgateway`.
`spec.allowedListeners`	Enable the attachment of ListenerSets to this Gateway. The example allows listeners from any namespace.
`spec.listeners`	Optionally, you can configure a listener that is specific to the Gateway. Note that due to a Gateway API limitation, you must configure at least one listener on the Gateway resource, even if the listener is not used and is a generic, “dummy” listener. This generic listener cannot conflict with the listener that you configure in the ListenerSet, such as using the same port or name. In this example, the generic listener is configured on port 80, which differs from port 443 in the ListenerSet that you create later.

Create a ListenerSet that configures a TLS passthrough listener for the Gateway.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XListenerSet
metadata:
  name: my-tls-listenerset
  namespace: kgateway-system
spec:
  parentRef:
    name: tls-passthrough
    namespace: kgateway-system
    kind: Gateway
    group: gateway.networking.k8s.io
  listeners:
  - protocol: TLS
    port: 8443
    hostname: nginx.example.com
    name: tls-listener-set
    tls:
      mode: Passthrough
    allowedRoutes:
      namespaces:
        from: All
EOF

Review the following table to understand this configuration.

Setting	Description
`spec.parentRef`	The name of the Gateway to attach the ListenerSet to.
`spec.listeners`	Configure the listeners for this ListenerSet. In this example, you configure a TLS passthrough listener for the `nginx.example.com` domain on port 8443.
`spec.listeners.tls.mode`	The TLS mode for incoming requests. TLS requests are passed through to the backend service without being terminated at the Gateway.

About AI for LLM consumption