gRPC routing

Route traffic to gRPC services by using the GRPCRoute resource for protocol-aware routing.

About gRPC routing

The GRPCRoute resource provides protocol-aware routing for gRPC traffic within the Kubernetes Gateway API. Unlike the HTTPRoute, which requires matching on HTTP paths and methods, the GRPCRoute allows you to define routing rules by using gRPC-native concepts, such as service and method names.

Consider the difference:

• HTTPRoute Match: path:/com.example.User/Login, method: POST
• GRPCRoute Match: service: yages.Echo, method: Ping

The GRPCRoute approach is more readable, less error-prone, and aligns with the Gateway API’s role-oriented philosophy.

Before you begin

1. Set up an agentgateway proxy.
2. Install the httpbin sample app.

Deploy a sample gRPC service

Deploy a sample gRPC service for testing purposes. The sample service has two APIs:

• yages.Echo.Ping: Takes no input (empty message) and returns a pong message.
• yages.Echo.Reverse: Takes input content and returns the content in reverse order, such as hello world becomes dlrow olleh.

Steps to set up the sample gRPC service:

1. Deploy the gRPC echo server and client.

   kubectl apply -f- <<EOF
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: grpc-echo
     namespace: agentgateway-system
     labels:
       app.kubernetes.io/name: grpc-echo
   spec:
     selector:
       matchLabels:
         app.kubernetes.io/name: grpc-echo
     replicas: 1
     template:
       metadata:
         labels:
          app.kubernetes.io/name: 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
     namespace: agentgateway-system
     labels:
       app.kubernetes.io/name: grpc-echo
   spec:
     type: ClusterIP
     ports:
       - port: 3000
         protocol: TCP
         targetPort: 9000
         appProtocol: kubernetes.io/h2c
     selector:
       app.kubernetes.io/name: grpc-echo
   ---
   apiVersion: v1
   kind: Pod
   metadata:
     name: grpcurl-client
     namespace: agentgateway-system
     labels:
       app.kubernetes.io/name: grpcurl-client
   spec:
    containers:
       - name: grpcurl
         image: docker.io/fullstorydev/grpcurl:v1.8.7-alpine
         command:
           - sleep
           - "infinity"
   EOF

2. Verify that the sample app is up and running.

   kubectl get pods -n agentgateway-system | grep grpc

   Example output:

   grpc-echo-5fc549b5fc-tdlzw            1/1     Running            0                39s
   grpcurl-client                        1/1     Running            0                6s
   

Set up gRPC routing

1. Create the GRPC Gateway. The following Gateway accepts routes from all namespaces.

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

2. Create the GRPCRoute. The GRPCRoute includes a match for grpc.reflection.v1alpha.ServerReflection to enable dynamic API exploration and a match for the Ping method. For detailed information about GRPCRoute fields and configuration options, see the Gateway API GRPCRoute documentation.

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

3. Verify that the GRPCRoute is applied successfully.

   kubectl get grpcroute example-route -n agentgateway-system -o yaml

   Example output:

   status:
     parents:
     - conditions:
       - lastTransitionTime: "2026-01-21T16:22:52Z"
         message: ""
         observedGeneration: 1
         reason: Accepted
         status: "True"
         type: Accepted
       - lastTransitionTime: "2026-01-21T16:22:52Z"
         message: ""
         observedGeneration: 1
         reason: ResolvedRefs
         status: "True"
         type: ResolvedRefs
       controllerName: agentgateway.dev/agentgateway
       parentRef:
         group: gateway.networking.k8s.io
         kind: Gateway
         name: grpc
         namespace: agentgateway-system
   

Verify the gRPC route

Verify that the gRPC route to the echo service is working. The steps vary whether your Gateway is exposed with a LoadBalancer service or set up for local testing only.

Cleanup

kubectl delete grpcroute example-route -n agentgateway-system
kubectl delete deployment grpc-echo -n agentgateway-system
kubectl delete service grpc-echo-svc -n agentgateway-system
kubectl delete pod grpcurl-client -n agentgateway-system
kubectl delete gateway grpc -n agentgateway-system