grpcurl fails with "server does not support the reflection API" in gRPC services documentation

[AryanParashar24]

grpcurl fails with "server does not support the reflection API" in gRPC services documentation

Description

When following the kgateway documentation for gRPC services (https://kgateway.dev/docs/main/traffic-management/destination-types/kube-services/grpc-services/), the provided grpcurl commands fail. The issue seems to be that the sample gRPC server image (ghcr.io/projectcontour/yages:v0.1.0) does not support the gRPC Reflection API, which grpcurl relies on for service discovery.

Steps to Reproduce

Apply the Kubernetes resources for the grpc-echo deployment, ReferenceGrant, and Gateway as outlined in the documentation.

kubectl apply commands for Deployment, ReferenceGrant, and Gateway...

Apply the GRPCRoute for the reflection API as shown in the documentation:

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

Run the grpcurl commands to test the reflection API and the Ping method:

grpcurl -insecure -authority grpc.example.com localhost:8443 list
grpcurl -insecure -authority grpc.example.com localhost:8443 describe yages.Echo
grpcurl -insecure -authority grpc.example.com localhost:8443 yages.Echo/Ping

Expected Behavior

The grpcurl commands should successfully list the available gRPC services, describe the yages.Echo service, and invoke the Ping method, returning a valid response.

Observed Behavior

All grpcurl commands fail with the following errors:

Failed to list services: server does not support the reflection API
Failed to resolve symbol "yages.Echo": server does not support the reflection API
Error invoking method "yages.Echo/Ping": failed to query for service descriptor "yages.Echo": server does not support the reflection API

Root Cause

The grpcurl tool relies on the gRPC Reflection API to discover services and their methods. The ghcr.io/projectcontour/yages:v0.1.0 image used in the example does not have the reflection service enabled, causing grpcurl to fail immediately. The GRPCRoute correctly forwards the reflection calls, but the backend is not configured to respond to them.

Suggested Solution

Updating Documentations with the following solutions can be adopted to solve the issue:

• Using a different gRPC test image that has the Reflection API enabled.

• Modifying the GRPCRoute example to use fullMethod matching for the Ping method, as the current example fails to provide a working end-to-end demonstration.

• Adding a note explaining that the yages service does not support reflection, and that users must provide a .proto file to grpcurl to bypass this.

[artberger]

Hi @AryanParashar24 , are you sure that the grpcurl failed because of this reflection API reason? I just ran through the guide and did not get that error.

% grpcurl -insecure -authority grpc.example.com localhost:8443 list

grpcurl -insecure -authority grpc.example.com localhost:8443 describe yages.Echo
grpc.health.v1.Health
grpc.reflection.v1alpha.ServerReflection
yages.Echo
yages.Echo is a service:
service Echo {
  rpc Ping ( .yages.Empty ) returns ( .yages.Content );
  rpc Reverse ( .yages.Content ) returns ( .yages.Content );
}

% grpcurl -insecure \
  -authority grpc.example.com \
  localhost:8443 \
  yages.Echo/Ping
{
  "text": "pong"
}