About the gRPC API

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

The gRPC API was changed in Gloo Edge 1.14. To learn more about the changes, see Changes to the gRPC API in Gloo Edge 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 Edge proxy to receive HTTP requests and transform them into gRPC requests, gRPC transcoding is used. With gRPC transcoding, you get the following benefits

Gloo Edge 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 Edge proxy. Gloo Edge 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:

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 Edge to route HTTP requests to your gRPC app. To configure your Gloo Edge 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 Edge provides the following options to discover the proto descriptors:

After the proto descriptor binary is discovered, Gloo Edge 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 Edge 1.14

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

Before Gloo Edge 1.14:

With Gloo Edge 1.14: