About the gRPC API

The gRPC API in Gloo Gateway allows you to expose gRPC services in your cluster so that client requests can be routed to your gRPC services. Gloo Gateway also supports HTTP to gRPC transcoding that lets you transform incoming HTTP requests into gRPC messages.

The gRPC API was changed in Gloo Gateway 1.14. To learn more about the changes, see Changes to the gRPC API in Gloo Gateway 1.14.

gRPC framework

gRPC is a popular open source high performance Remote Procedure Call (RPC) framework that can run in any environment and is commonly used to connect microservices within and across data centers. With gRPC, you get the following advantages:

gRPC transcoding

While gRPC works great for internal microservice communication, most internet-facing clients use the HTTP REST API to send and receive requests. To enable your Gloo Gateway proxy to receive HTTP requests and transform them into gRPC requests, gRPC transcoding is used. With gRPC transcoding, you get the following benefits

Gloo Gateway allows you to add HTTP rules and mappings to your gRPC API, and to automatically transform and route HTTP requests to gRPC services at no additional cost. Internet-facing clients can send an HTTP request with tools, such as curl, to your Gloo Gateway proxy. Gloo Gateway uses the HTTP mappings that you defined and maps the HTTP request to gRPC message fields. The request is then forwarded to the gRPC services where it is processed.

HTTP rules and mappings

To map HTTP to gRPC methods, you add an HTTP rule to your proto file. An HTTP rule describes how a component of a gRPC request is mapped to an HTTP URL path, URL query parameter, or request body. The HTTP rule also describes how gRPC response messages are mapped to the HTTP response body.

To define an HTTP rule in your proto file, you add the google.api.http annotation to your gRPC method as shown in the followimg example.

     service Messaging {
       rpc GetMessage(GetMessageRequest) returns (Message) {
         option (google.api.http) = {
             get: "/v1/{name=messages/*}"
         };
       }
     }
     message GetMessageRequest {
       string name = 1; // Mapped to URL path.
     }
     message Message {
       string text = 1; // The resource content.
     }

With this code, you can achieve the following HTTP to gRPC mapping:

HTTP gRPC
curl -X GET http://{DOMAIN_NAME}/v1/messages/123456 GetMessage(name: "messages/123456")

To learn more about HTTP to gRPC transcoding and find other examples, see the Transcoding reference.

HTTP mapping discovery

Adding HTTP mappings to your proto files does not automatically set up Gloo Gateway to route HTTP requests to your gRPC app. To configure your Gloo Gateway proxy to accept incoming HTTP requests for your gRPC app and to correctly translate the HTTP request into a gRPC request, the gateway requires proto descriptors to be present on the gRPC upstream. Proto descriptors are generated by using the protoc tool based on what you defined in your proto files and must be encoded to base64 before they are added to the gRPC upstream.

Depending on your setup, Gloo Gateway provides the following options to discover the proto descriptors:

After the proto descriptor binary is discovered, Gloo Gateway is configured to accept incoming HTTP requests and translate these requests to gRPC requests so that they can be processed by the gRPC upstream.

Changes to the gRPC API in Gloo Gateway 1.14

The following changes were introduced to the gRPC API in Gloo Gateway 1.14:

Before Gloo Gateway 1.14:

With Gloo Gateway 1.14: