Transcode HTTP to gRPC

gRPC is a remote procedure call framework that uses HTTP/2 for transport and Protocol Buffers to define services and message types.

The grpc-transcode plugin lets an HTTP client call a gRPC service through APISIX. APISIX encodes the HTTP request as a gRPC message, sends it to the configured method, and decodes the response as JSON.

Prerequisite(s)

• Install Docker.
• Install cURL to send requests to APISIX for validation.
• Install jq to embed the .proto definition in an Admin API request.
• Install gRPCurl to call the example gRPC service directly.
• Follow the Getting Started tutorial to start APISIX in Docker. The commands below use the apisix-quickstart-net network created by that tutorial.
• If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY. The Docker quickstart disables authentication for local evaluation; keep it enabled in production.

Deploy an Example gRPC Server

Start the example gRPC server in the APISIX quickstart network. The image digest pins the tested contents of tag 1.0.2:

docker rm -f quickstart-grpc-example 2>/dev/null || true

docker run -d --rm \
  --name quickstart-grpc-example \
  --network apisix-quickstart-net \
  -p 50051:50051 \
  api7/grpc-server-example:1.0.2@sha256:9d822f5957724d2b9f668e81d5cd221e030a7155ac5558b56f1a07cb9e8cbbce

The server exposes echo.EchoService. Its Echo method accepts an EchoMsg message and returns the same message type.

Call the method directly with gRPCurl:

grpcurl -plaintext \
  -d '{"msg":"Hello"}' \
  "127.0.0.1:50051" \
  "echo.EchoService/Echo"

The server should return the message:

{
  "msg": "Hello"
}

Create a Proto Object

Save the service definition as echo.proto:

echo.proto

cat > echo.proto <<'EOF'
syntax = "proto3";

package echo;

service EchoService {
  rpc Echo (EchoMsg) returns (EchoMsg);
}

message EchoMsg {
  string msg = 1;
}
EOF

Create a proto object with the ID quickstart-proto:

jq -n --rawfile content echo.proto \
  '{id: "quickstart-proto", content: $content}' \
  | curl -i "http://127.0.0.1:9180/apisix/admin/protos" -X PUT \
    -H "X-API-KEY: ${ADMIN_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-binary @-

An HTTP/1.1 201 Created response verifies that APISIX stored the proto object.

Configure grpc-transcode

Create a route that maps GET /echo to echo.EchoService/Echo:

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "id": "quickstart-grpc",
  "methods": ["GET"],
  "uri": "/echo",
  "plugins": {
    "grpc-transcode": {
      "proto_id": "quickstart-proto",
      "service": "echo.EchoService",
      "method": "Echo"
    }
  },
  "upstream": {
    "scheme": "grpc",
    "type": "roundrobin",
    "nodes": {
      "quickstart-grpc-example:50051": 1
    }
  }
}
EOF

❶ Load the service definition from the quickstart-proto proto object.

❷ Select the fully qualified gRPC service name.

❸ Select the method to invoke on that service.

An HTTP/1.1 201 Created response verifies that APISIX created the route.

Verify HTTP-to-gRPC Transcoding

Send an HTTP request with the EchoMsg.msg field as a query parameter:

curl -i "http://127.0.0.1:9080/echo?msg=Hello"

APISIX should return HTTP 200 with the decoded gRPC response:

{
  "msg": "Hello"
}

Next Steps

The grpc-transcode plugin supports additional request and response options. See the grpc-transcode Plugin Hub reference for configuration details and examples.

For browser clients, APISIX supports gRPC-Web, which adapts the native gRPC protocol. Configure it with the grpc-web plugin.