Version: latest

Configure gRPC Proxying

API7 Enterprise supports proxying gRPC traffic, allowing you to manage gRPC services with the same traffic management, security, and observability features as your HTTP services. You can also transcode RESTful HTTP requests to gRPC and enable gRPC-Web support for browser-based clients.

Prerequisites

An API7 Enterprise instance is running.
A Gateway Group is created and a Gateway instance is running.
A token from the Dashboard.
grpcurl is installed if you want to validate the sample gRPC server directly and test native gRPC proxying.

Start a Sample gRPC Server

Start the same sample gRPC server used in the API7 Enterprise gRPC best-practice guide:

docker run -d \
  --name grpc-service \
  -p 50051:50051 \
  api7/grpc-server-example:1.0.0

This server exposes the helloworld.Greeter service and the SayHello method used in the examples below.

You can verify the upstream directly with grpcurl:

grpcurl -plaintext 127.0.0.1:50051 list helloworld.Greeter

The examples below assume the gateway can reach the Docker host at host.docker.internal. If your environment uses a different host address, replace host.docker.internal with that address.

Enable an HTTP/2 Listener for Native gRPC

For native gRPC and gRPC-Web validation, the gateway must accept HTTP/2 traffic on a listener that clients can reach. In Docker-based local setups, publish an additional port such as 9081 and enable HTTP/2 on that port.

If your gateway container is already running, recreate it with -p 9081:9081, then update the gateway configuration:

docker exec <gateway-container-name> /bin/sh -c "cat > /usr/local/apisix/conf/config.yaml <<'EOF'
nginx_config:
  error_log_level: warn

apisix:
  node_listen:
    - port: 9080
      enable_http2: true
    - port: 9081
      enable_http2: true
EOF"

docker exec <gateway-container-name> apisix reload

Use the new 9081 listener for native gRPC validation.

Basic gRPC Proxying

To proxy gRPC traffic, you need to set the upstream scheme to grpc or grpcs (for encrypted gRPC).

Configure a gRPC Service and Route

Create a Service with the grpc scheme and a Route that points to it.

Admin API
ADC

# 1. Create a gRPC Service
curl -k "https://localhost:7443/apisix/admin/services/grpc-service?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "grpc-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "grpc",
      "nodes": [
        {
          "host": "host.docker.internal",
          "port": 50051,
          "weight": 100
        }
      ]
    }
  }'

# 2. Create a Route for the Service
curl -k "https://localhost:7443/apisix/admin/routes/grpc-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "grpc-route",
    "methods": ["GET", "POST"],
    "paths": ["/helloworld.Greeter/SayHello"],
    "service_id": "grpc-service"
  }'

adc.yaml
services:
  - name: grpc-service
    upstream:
      scheme: grpc
      type: roundrobin
      nodes:
        - host: host.docker.internal
          port: 50051
          weight: 100
    routes:
      - name: grpc-route
        uris:
          - /helloworld.Greeter/SayHello
        methods:
          - GET
          - POST

adc sync -f adc.yaml

REST-to-gRPC Transcoding

The grpc-transcode plugin allows you to expose gRPC services as RESTful APIs. The Gateway handles the conversion between HTTP/JSON and gRPC/Protobuf.

Step 1: Upload the Proto Definition

First, upload your .proto file content to the gateway.

Admin API
ADC

curl -k "https://localhost:7443/apisix/admin/protos/helloworld-proto?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "helloworld-proto",
    "content": "syntax = \"proto3\";\n\npackage helloworld;\n\nservice Greeter {\n  rpc SayHello (HelloRequest) returns (HelloReply) {}\n}\n\nmessage HelloRequest {\n  string name = 1;\n}\n\nmessage HelloReply {\n  string message = 1;\n}"
  }'

caution

ADC currently does not support protobuf resources. Upload protobuf definitions through the Admin API first, then reference the uploaded proto_id from ADC-managed routes.

Step 2: Configure the Route with grpc-transcode

Create a Route and enable the grpc-transcode plugin, referencing the proto_id, service name, and method.

Admin API
ADC

curl -k "https://localhost:7443/apisix/admin/routes/grpc-transcode-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "grpc-transcode-route",
    "methods": ["POST"],
    "paths": ["/hello"],
    "service_id": "grpc-service",
    "plugins": {
      "grpc-transcode": {
        "proto_id": "helloworld-proto",
        "service": "helloworld.Greeter",
        "method": "SayHello"
      }
    }
  }'

adc.yaml
routes:
  - name: grpc-transcode-route
    uri: /hello
    service_name: grpc-service
    plugins:
      grpc-transcode:
        _state: enabled
        proto_id: helloworld-proto
        service: helloworld.Greeter
        method: SayHello

adc sync -f adc.yaml

gRPC-Web for Browser Clients

The grpc-web plugin allows browser-based clients to interact with gRPC services using the gRPC-Web protocol.

Admin API
ADC

curl -k "https://localhost:7443/apisix/admin/routes/grpc-web-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "grpc-web-route",
    "methods": ["GET", "POST"],
    "paths": ["/helloworld.Greeter/SayHello"],
    "service_id": "grpc-service",
    "plugins": {
      "grpc-web": {
        "cors_allow_headers": "content-type,x-grpc-web,x-user-agent"
      }
    }
  }'

adc.yaml
routes:
  - name: grpc-web-route
    uri: /helloworld.Greeter/SayHello
    service_name: grpc-service
    plugins:
      grpc-web:
        _state: enabled
        cors_allow_headers: "content-type,x-grpc-web,x-user-agent"

adc sync -f adc.yaml

Validate the Configuration

After you provision the sample gRPC upstream and upload the matching protobuf definition, you can test the REST-to-gRPC transcoding by sending a standard HTTP POST request to the configured route.

curl -X POST http://localhost:9080/hello -d '{"name": "API7"}'

The Gateway transcodes the JSON body to a Protobuf message, calls the gRPC service, and returns the response as JSON:

{"message": "Hello API7"}

To validate native gRPC proxying, first enable a client-facing HTTP/2 listener such as 9081 on the gateway, then send a request with grpcurl:

grpcurl -plaintext \
  -proto helloworld.proto \
  -d '{"name":"API7"}' \
  127.0.0.1:9081 \
  helloworld.Greeter.SayHello

Next Steps

Configure WebSocket Proxying — learn how to handle long-lived WebSocket connections.
Configure GraphQL Proxying — explore GraphQL-aware traffic management.

Prerequisites​

Start a Sample gRPC Server​

Enable an HTTP/2 Listener for Native gRPC​

Basic gRPC Proxying​

Configure a gRPC Service and Route​

REST-to-gRPC Transcoding​

Step 1: Upload the Proto Definition​

Step 2: Configure the Route with grpc-transcode​

gRPC-Web for Browser Clients​

Validate the Configuration​

Next Steps​