gRPC

gRPC is an RPC framework from Google. It uses protocol buffers as the underlying serialization/IDL format. At the transport layer it uses HTTP/2 or above for request/response multiplexing. Envoy has first class support for gRPC both at the transport layer as well as at the application layer:

  • gRPC makes use of trailers to convey request status. Envoy is one of very few HTTP proxies that correctly supports trailers and is thus one of the few proxies that can transport gRPC requests and responses.

  • The gRPC runtime for some languages is relatively immature. See below for an overview of filters that can help bring gRPC to more languages.

  • gRPC-Web is supported by a filter that allows a gRPC-Web client to send requests to Envoy over HTTP/1.1 and get proxied to a gRPC server. It’s under active development and is expected to be the successor to the gRPC bridge filter.

  • gRPC-JSON transcoder is supported by a filter that allows a RESTful JSON API client to send requests to Envoy over HTTP and get proxied to a gRPC service.

  • gRPC-JSON reverse transcoder is supported by a filter that allows a gRPC client to send requests to Envoy and get proxied to a RESTful JSON API service.

gRPC bridging

Envoy supports multiple gRPC bridges:

  • grpc_http1_bridge filter which allows gRPC requests to be sent to Envoy over HTTP/1.1. Envoy then translates the requests to HTTP/2 or HTTP/3 for transport to the target server. The response is translated back to HTTP/1.1. When installed, the bridge filter gathers per RPC statistics in addition to the standard array of global HTTP statistics.

  • grpc_http1_reverse_bridge filter which allows gRPC requests to be sent to Envoy and then translated to HTTP/1.1 when sent to the upstream. The response is then converted back into gRPC when sent to the downstream. This filter can also optionally manage the gRPC frame header, allowing the upstream to not have to be gRPC aware at all.

  • connect_grpc_bridge filter which allows Connect requests to be sent to Envoy. Envoy then translates the requests to gRPC to be sent to the upstream. The response is converted back into the Connect protocol to be sent back to the downstream. HTTP/1.1 requests will be upgraded to HTTP/2 or HTTP/3 when needed.

gRPC services

In addition to proxying gRPC on the data plane, Envoy makes use of gRPC for its control plane, where it fetches configuration from management server(s) and in filters, such as for rate limiting or authorization checks. We refer to these as gRPC services.

When specifying gRPC services, it’s necessary to specify the use of either the Envoy gRPC client or the Google C++ gRPC client. We discuss the tradeoffs in this choice below.

The Envoy gRPC client is a minimal custom implementation of gRPC that makes use of Envoy’s HTTP/2 or HTTP/3 upstream connection management. Services are specified as regular Envoy clusters, with regular treatment of timeouts, retries, endpoint discovery/load balancing/failover/load reporting, circuit breaking, health checks, outlier detection. They share the same connection pooling mechanism as the Envoy data plane. Similarly, cluster statistics are available for gRPC services. Since the client is minimal, it does not include advanced gRPC features such as OAuth2 or gRPC-LB lookaside.

The Google C++ gRPC client is based on the reference implementation of gRPC provided by Google at https://github.com/grpc/grpc. It provides advanced gRPC features that are missing in the Envoy gRPC client. The Google C++ gRPC client performs its own load balancing, retries, timeouts, endpoint management, etc, independent of Envoy’s cluster management. The Google C++ gRPC client also supports custom authentication plugins.

It is recommended to use the Envoy gRPC client in most cases, where the advanced features in the Google C++ gRPC client are not required. This provides configuration and monitoring simplicity. Where necessary features are missing in the Envoy gRPC client, the Google C++ gRPC client should be used instead.