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.

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:

• Automatic generation of client and server stubs.
• Efficient binary protocols with Google’s protobufs.
• Cross-language support, as client and server libraries are available in many languages.
• Support for HTTP transcoding to support firewalls and load balancers.
• Integrated with common observability tools, such as Prometheus.

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

• Build one service that supports both gRPC and REST API requests and responses.
• Provide a more web-friendly API to clients.
• Keep your app backwards-compatible.
• Support low-end devices that do not support the gRPC protocol.

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:

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:

• Automatic discovery with FDS: You can enable the Gloo Gateway Function Discovery Service (FDS) to automatically discover gRPC functions and HTTP mappings in your proto files and to generate proto descriptors from them. The proto descriptors are automatically added to the gRPC upstream.
• Manual discovery without FDS: If you do not or cannot enable Gloo Gateway FDS, you can manually generate proto descriptors, encode them to base64, and add them to the upstream. This way, you manually configure the Envoy filter that handles the HTTP to gRPC transcoding. Note that any proto descriptors that you added to the upstream are overwritten when you enable FDS.

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:

• You did not have to provide HTTP mappings in the gRPC proto files. Instead, Gloo Gateway used the functions that were available in the proto file and the HTTP mapping that you provided in the Virtual Service to derive the proto descriptors. Proto descriptors were then automatically added to the gRPC upstream.
• When you disabled FDS and manually generated the proto descriptors, you had the option to add the proto descriptors to the gateway resource instead of the gRPC upstream.

With Gloo Gateway 1.14:

• HTTP mappings must always be provided in the proto itself. Gloo Gateway supports automatic and manual discovery of proto descriptors as described in HTTP mapping discovery.
• If you added your HTTP mappings to the virtual service in an earlier release of Gloo Gateway, Gloo Gateway does not automatically discover these mappings anymore to automatically derive the proto descriptors. If you plan to upgrade to Gloo Gateway 1.14, make sure that you add your HTTP mappings to the proto file directly.
• The feature in the gRPC API to add proto descriptor binaries to the gateway resource instead of an upstream remains unchanged. If you have existing gateway resources with proto descriptors they continue to function. While this feature is still supported, it is recommended to add the proto descriptors to the upstream directly to control each individual gRPC service separately.