.. _arch_overview_grpc:
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 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 HTTP/2 trailers to convey request status. Envoy is one of very few HTTP proxies
that correctly supports HTTP/2 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. Envoy supports a gRPC :ref:`bridge
filter ` that allows gRPC requests to be sent to Envoy over
HTTP/1.1. Envoy then translates the requests to HTTP/2 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-Web is supported by a :ref:`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 :ref:`bridge filter
`.
* gRPC-JSON transcoder is supported by a :ref:`filter `
that allows a RESTful JSON API client to send requests to Envoy over HTTP and get proxied to a
gRPC service.
.. _arch_overview_grpc_services:
gRPC services
-------------
In addition to proxying gRPC on the data plane, Envoy make use of gRPC for its
control plane, where it :ref:`fetches configuration from management server(s)
` and also in filters, for example for :ref:`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
:ref:`Envoy gRPC client ` or the
:ref:`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 upstream connection management. Services are specified as
regular Envoy :ref:`clusters `, with regular
treatment of :ref:`timeouts, retries `, endpoint
:ref:`discovery `/:ref:`load
balancing/failover `/load reporting, :ref:`circuit
breaking `, :ref:`health checks
`, :ref:`outlier detection
`. They share the same :ref:`connection pooling
` mechanism as the Envoy data plane. Similarly, cluster
:ref:`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.