Proxy gRPC Services

Google Remote Procedure Call (gRPC) is an open-source high-performance Remote Procedure Call (RPC) framework based on HTTP/2 protocol. It uses Protocol Buffers (protobuf) as the Interface Description Language (IDL). API7 Enterprise provides crucial functionalities such as protocol conversion, load balancing, authentication, and authorization, enhancing the potential of gRPC.

This guide shows how to use API7 Enterprise to proxy gRPC services.

Prerequisites

• Install API7 Enterprise.
• Install gRPCurl to send requests to gRPC services for validation.

Deploy a gRPC Server Example

1. Start a gRPC server example.

   API7 provides a gRPC service example for testing. You can start a gRPC server Docker instance example to run a service grpc-service on port 50051 using the following command:

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

2. Verify whether the gRPC server starts successfully by listing available gRPC services and methods:

   • gRPC services

     grpcurl -plaintext 127.0.0.1:50051 list

     You should see the following output:

     grpc.reflection.v1alpha.ServerReflection
     helloworld.Greeter
     helloworld.TestImport

   • gRPC methods

     grpcurl -plaintext 127.0.0.1:50051 list helloworld.Greeter

     You should see the following output:

     helloworld.Greeter.GetErrResp
     helloworld.Greeter.Plus
     helloworld.Greeter.SayHello
     helloworld.Greeter.SayHelloAfterDelay
     helloworld.Greeter.SayHelloBidirectionalStream
     helloworld.Greeter.SayHelloClientStream
     helloworld.Greeter.SayHelloServerStream

Update API7 Gateway Instance

By default, API7 gateway instance supports TLS-encrypted HTTP/2 on port 9443. In this tutorial, you can add port 9081 to support non-encrypted HTTP/2 and then expose port 9081 to the same port on the host machine.

config.yaml

apisix:
  node_listen:
    - port: 9080
      enable_http2: false
    - port: 9081
      enable_http2: true

Rerun the docker-compose up -d command in the api7-ee directory to update API7 gateway configurations.

Create a Service and a Route

This example creates a service named grpc-example and a route named helloworld.Greeter.

1. Go to the API7 Dashboard.
2. Create a service.
   1. Select Services from the side navigation bar and then click Add Service.
   2. Select Add Manually.
   3. From the Add Service dialog box, do the following:
      • In the Name field, enter grpc-example.
      • In the Upstream Scheme field, choose gRPC.
   4. Click Add.
3. Create a route.
   1. Click the service that you just created in the previous step and then click Add Route.
   2. From the Add Route dialog box, do the following:
      • In the Name field, enter helloworld.Greeter.
      • In the Path field, enter /helloworld.Greeter/SayHello.
      • In the Methods field, choose GET and POST.
   3. Click Add.

Publish Service

1. Select Services from the side navigation bar and then click Publish Now for the grpc-example service.
2. Choose the default gateway group and then click Next.
3. From the dialog box, do the following:
   • In the New Version field, enter 1.0.0.
   • In the How to find the upstream field, choose Use Nodes.
4. From the Add Node dialog box, do the following:
   • In the Host field, enter your local host IP address.
   • In the Port field, enter 50051.
   • In the Weight field, use the default value 100.
5. Click Add.
6. Confirm the service information, then click Publish.

Validate gRPC Service

This example uses the helloworld.proto file to ensure the gRPCurl CLI tool aligns the request and response format with the gRPC service definition. You can find an example helloworld.proto file here.

grpcurl -plaintext -proto helloworld.proto -d '{"name":"apisix"}' 127.0.0.1:9081 helloworld.Greeter.SayHello  # Replace 127.0.0.1 to your local host IP address

You should see the following output:

{
  "message": "Hello apisix"
}

Related Topic

To learn how to use the grpc-transcode plugin to transform between RESTful HTTP requests and gRPC requests, see related docs (coming soon).