Spring Cloud Gateway Tutorial

Before we dive in to nitty gritty details of spring cloud gateway, let’s touch up on some basics around reverse proxy and api gateway pattern.

What is Reverse Proxy?

Reverse proxy is something that is making requests on behalf of something else. It acts more like simple routing. It can add basic security and monitoring but can’t really do some of the advanced things like mediation or orchestration. NGINX is one of the well known reverse proxy server.

What is API Gateway?

In plain terms, API Gateway is enhanced reverse proxy with more advanced capabilities including orchestration and added security and monitoring capabilities. Netflix Zuul, Amazon API Gateway, Apigee and of course Spring Cloud Gateway are few of well known api gateway implementation.

So, what is Spring Cloud Gateway?

Spring Cloud Gateway is API Gateway implementation by Spring Cloud team on top of Spring reactive ecosystem. It provides a simple and effective way to route incoming requests to the appropriate destination using Gateway Handler Mapping.

And Spring Cloud Gateway uses Netty server to provide non-blocking asynchronous request processing.

Below is high level flow of how request routing works in Spring Cloud Gateway:

Spring Cloud Gateway Architecture

Spring Cloud Gateway consists of 3 main building blocks:

Route: Think of this as the destination that we want a particular request to route to. It comprises of destination URI, a condition that has to satisfy — Or in terms of technical terms, Predicates, and one or more filters.

Predicate: This is literally a condition to match. i.e. kind of “if” condition..if requests has something — e.g. path=blah or request header contains foo-bar etc. In technical terms, it is Java 8 Function Predicate

Filter: These are instances of Spring Framework WebFilter. This is where you can apply your magic of modifying request or response. There are quite a lot of out of box WebFilter that framework provides. But of course, we are talking about Spring Framework. So, rest easy folks!!! You can always add your own filter with your own logic :)

Spring Cloud Gateway vs. Zuul:

I know you all who are using Spring boot must be wondering, we are already using Zuul. And it pretty much provides the same functionality as Spring Cloud Gateway. So, why do we switch to a new framework?

The main reason to me is — Zuul 1.x is not reactive. It is blocking. Now if you are moving to Reactive pattern to get better performance from your microservices and you are using Spring boot 2 with Reactor — you can use Zuul 2.0 which does have Reactive non blocking support with netty.

But Spring ecosystem does not have in-built support like Zuul 1.x. This means, you will have to run your own separate service just with Zuul. You can’t make it integrated with other existing spring microservice. And Spring team is not planning to add support for it with Spring reactive.

This means, if you are like me and moving to Spring reactive, I would advise to use Spring Cloud Gateway as it can integrate with any microservice and make it true api gateway with adding authentication and other security features at one place.

I guess we’ve done enough talking. Let’s dive in to some real code samples:

What are we using:

• Java 1.8
• Spring boot 2.1.5 with WebFlux

Let’s first create 2 simple microservices with each having at least one REST endpoint. For now we’ll just have simple System.out and then we’ll go on adding more things to it:

Microservice 1: Just try to run this manually to make sure all is well with this service and we can hit it and get response.

And don’t worry about that code printing request headers. We will cover that in later section of this tutorial

Microservice 2: Do the same with this service as well and make sure it is up and running.

Spring Cloud Gateway:

Now, this is where the routing magic will happen. You can do route configuration in spring cloud gateway using one of the two following options:

• programmatically using Spring RouteLocator. But problem with this is that every time you need to add or update a route, you will have to redeploy the whole application.
• Using application.properties (or application.yml) configuration file. And this is the approach we are going to take for this tutorial.

Below is application.yml file for the gateway application. Don’t worry because we are going to break it down and understand.

sc-gw-application-yml

• server.port is very basic and everyone working with spring boot will know that.
• But next few lines are specific to Spring cloud gateway and very important. As mentioned earlier, there are 3 major components of spring cloud gateway framework. And Route is main one.
• So, here we are telling gateway, what all destination, request need to be routed.
• id — this should be unique id of any route. For simplicity, we are giving the same name as the root context of our microservice 1
• uri — the uri where our microservice is running. Please pay attention here that we don’t need to give full context root. This should be just the hostname
• predicates — This is the condition that we want to check before routing to this uri/route. Any web application developer would be familiar with this syntax as it is same as what we used to mention in web.xml in good old plain servlet/Struts/Spring MVC days.

Spring Cloud Gateway framework has many built in Predicate factories and you can get more information on them from its documentation. Here we are using one of them — Path. But as it says, you can have more than one predicates to check for any routing.

Wait.. is there something missing? As per my earlier explanation, there are 3 parts. But here we mentioned only 2. The third one — filters — where are they ? Be patient friends.. We’ll go step by step.

So, let’s start all 3 applications and hit both microservice endpoints using gateway url and see what we get :

• microservice 1 is started at port 9091
• microservice 2 is started at port 9092
• gateway is started at port 9090

And below is a screenshot of hitting microservice 1 and 2 endpoint using gateway port 9090

Excellent!!! We are progressing. Now that we have gotten something going, let’s move to our next step.

We need to add filters to our route now. There are 2 different types of filters.

• Pre Filters — if you want to add or change request object before you pass it down to destination service, you can use these filters.
• Post Filters — if you want to add or change response object before you pass it back to client, you can use these filters.

We will create both of these types of filters for understanding.

Also, you can apply filters to specific route or you can make filters execute for all routes. We call this Global Filter. We will create one Global Filter as well.

Spring Cloud Gateway includes many built in factory classes for different filters. And you can extend those filter factories to create your own custom Filters. We are going to extend AbstractGatewayFilterFactory for our custom filters :

SCGWPreFilter:

SCGWPostFilter:

SCGWGlobalFilter:

Finally, we’ve got to update our configuration — i.e. application.yml to inform our gateway when and what filters need to be applied to what route

application.yml

As you can see above, we’ve added 2 new items in the yml.

1. Configuration telling to apply Global Filters to all routes
2. Two filters to route with id of nt-ms1 only.

Let’s make one small change in Microservice 1 endpoint to add Cookie in response header. This way, we can check the execution of Post Filter and print this header.

Now, we can run the applications again and verify the execution of filter.

Microservice 1 Logs:

Now this is the time our code for printing request headers will come in to play. If you check the logs of microservice 1 endpoint, it will have headers from both Global filter as well as Pre Filter.

Gateway logs:

Microservice 2 Logs:

As you can see here in the logs, we only see request headers from Global Filter. And no response header from Post Filter either.

I will conclude this tutorial here. There are more items to explore — like https connection to microservices, monitoring gateway using actuator and of course checking all out of the box gateway factories. And you can find all that on spring cloud gateway documentation.

But I am sure, this article will help you get going and explore these items on your own.

You can find all of the source code I have done on github.

Enjoy and Happy Springing!!!

References:

• Spring cloud gateway — https://cloud.spring.io/spring-cloud-gateway/spring-cloud-gateway.html
• Building Gateway — https://spring.io/guides/gs/gateway/
• Spring Cloud Gateway GitHub Repo — https://github.com/spring-cloud/spring-cloud-gateway
• Netty framework — https://netty.io/index.html