Starting from version 3.1.0 as part of the Spring Cloud 2021.0.0 (aka Jubilee) release train, Spring Cloud Gateway included support for gRPC and HTTP/2.
We will introduce the basic concepts behind gRPC and how to configure it with two examples:
- One that showcases how Spring Cloud Gateway can transparently re-route gRPC traffic without needing to know the proto definition and without having to modify our existing gRPC servers.
- Another that showcases how we can create a custom filter in Spring Cloud Gateway to transform a JSON payload to a gRPC message.
Introduction to gRPC and HTTP/2
HTTP/2 makes our applications faster, simpler, and more robust. Reducing latency by enabling request and response multiplexing, adding efficient compression of HTTP header fields, and adding support for request prioritization and server push.
The reduction in the number of connections is particularly important when improving the performance of HTTPS: that way we have less expensive TLS handshakes, more efficient session reuse, reducing client and server resources.
HTTP/2 provides two mechanisms for negotiating the application level protocol:
H2CHTTP/2.0 support with clear-text
H2HTTP/2.0 support with TLS
reactor-netty has support for
H2C clear-text protocol, Spring Cloud Gateway requires
H2 with TLS to assure transport security.
HTTP/2 adds a binary framing layer, which is how the HTTP messages are encapsulated and transferred between the client and server, enabling more efficient ways to transfer data.
Thanks to reactor-netty and its HTTP/2 support, we were able to extend Spring Cloud Gateway to support gRPC.
gRPC is a high-performance Remote Procedure Call framework that can run in any environment. It provides bi-directional streaming, and it’s based on HTTP/2.
gRPC services can be defined using Protocol Buffers, a powerful binary serialization toolset and language, and provides tools for generating clients and servers across different languages.
In order to enable gRPC in Spring Cloud Gateway, we need to enable HTTP/2 and SSL in our project by adding a keystore, this can be done through configuration by adding the following:
Now that we have it enabled, we can create a route that redirects traffic to a gRPC server and take advantage of the existing filters and predicates, for example, this route will redirect traffic that comes from any path starting with
grpc to a local server in the port
6565 and add header
X-Request-header with the value
Running gRPC to gRPC
An end to end example can be found in this repository with the following parts:
grpc-serverthat exposes a
HelloService, and gRPC endpoint to receive a
HelloRequestand return a
The server will concatenate a salutation with
firstName and a
lastName and respond with a
For example, this input:
grpc-client, in charge of sending the
grpc-simple-gatewaythat routes the requests and adds a header with the configuration mentioned above. Note that this gateway application does not have any dependency to gRPC nor to the proto definition used by client and server.
At the moment there is just one route that will forward everything to the
To start the server that is going to be listening to requests:
Then, we start the gateway that is going to re-route the gRPC requests:
Finally, we can use the client that points to the gateway application:
The gateway routes and filters can be modified in grpc-simple-gateway/src/main/resources/application.yaml
Running JSON to gRPC with a custom filter
Thanks to Spring Cloud Gateway flexibility, it is possible to create a custom filter to transform from a JSON payload to a gRPC message.
Even though it will have a performance impact since we have to serialize and deserialize the requests in the gateway and creating a channel from it, it is a common pattern if you want to expose a JSON API while maintaining internal compatibility.
For that, we can extend our
grpc-json-gateway to include the
proto definition with the message we want to send.
Spring Cloud Gateway contains a mechanism to create custom filters allowing us to intercept requests and add custom logic to them.
For this particular scenario, we are going to deserialize the JSON request and create a gRPC channel that will send a message to the
The full implementation can be found in: grpc-json-gateway/src/main/java/com/example/grpcserver/hello/JSONToGRPCFilterFactory.java
Using the same
grpc-server , we can start the gateway with the custom filter with:
And send JSON requests to the
grpc-json-gateway using, for example,
We see how the gateway application forwards the requests and returns the JSON payload with the new
In this post, we’ve looked at a few examples of how gRPC can be integrated within Spring Cloud Gateway. I’d love to know what other usages you’ve found to be helpful in your experiences.