Blog de Nicolas DUMINIL

Lasciate ogni speranza vuoi che entrate qui !

Basics of Microservices - Part 5: The Netflix Zuul Service

Publié le 11/08/2018

In the Part 3 of these article series (, we demonstrated how to load-balance between micro-services instances, using he Netfkix Eureka service. This way we achieved one of the most important goals of the Service Orientated Architecture: the services virtualization and their location transparency. The Part 4 ( showed how to use the Netflix Hystrix service  in order to improve microservices resilience.

Netflix Zuul is a so-called API Gateway, i.e. an intermediary component sitting between micrsoervices and their consumers.

Until now, while testing our microservices, we have either called them directly or via the Eureka discovery service. 
A microservices gateway is a mediator between the microservices and their consumers. This way we have a single URL that the consumers call and this provides us with one of the Graal of the SOA which is the location transparency. Should the location of our services change, and this is something which happens more often then we might think it does, the consumers will consider to work as expected, which wouldn't have been the case if the consumers would have consumed the services directly, without a gateway.

Another considerable advantage when using a microservices gateway is that it acts as a single, central, policy enforcement point. Hence, should we want to secure the access to the microservices, or should we want to perform advanced logging or tracing, this is the point where we can do it without affecting the global design.

Spring Cloud integrates with the Zuul Netflix project. This is an open source project providing a microservices gateway such the one we described above. It is very simple to set it up via Spring Cloud annotations, as follows.

Our sample microservice was initially consumed directly (in the Part 1 of the article series). In this scenario, our consumer used the microservice effective URL in order to invoke it. Later, in the Part 3, we added a 2nd instance of our sample microservice and then we couldn't consume them directly as, for doing that, our consumer would have to "know" that there are several instances of the microservice and to choose between these instances the one to be called. And as this cannot be an option, we introduced the Eureka autodiscovery service. This service is designed, as seen in the Part 3, such that to inspect the running services and, by interacting with them, to build a services map with their associated status. Hence, consumers just invoke the Eureka autodiscovery service URL, by specifying the generic name of the microservice to be called and the requests are forwarded to the most appropriated running instance of this microservice.

Using the Eureka autodiscovery service provided us with things like services virtualization and location transparency. But we need more then that. We need a single and centralized policy enforcing point where we could apply security or logging/tracing policies, without touching the microservcices.

In order to do that, we modified our project such that to add a new maven module, named ms-routing. Netflix Zuul is completely integrated with Spring Cloud and, in order to use this integration, we need to include the following dependency:


Next, we implemented the Zuul gateway service as a Spring Boot application which code is presented below:

package fr.simplex_software.micro_services.routing;

import org.springframework.beans.factory.annotation.*;
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.context.annotation.*;
import org.springframework.web.client.*;

public class RoutingServerApplication
@ Bean
  public RestTemplate getRestTemplate()
   return new RestTemplate();

  public static void main(String[] args)
  {, args);

That’s all we need in order to define a gateway service. This code will run an embedded tomcat container having deployed in it a microservice named RoutingServerApplication. This microservice is our gateway service, the one that the consumers will call in order to get the target endpoints. Here is how: 

  image: openjdk:8-jdk-alpine
   - ms-config
   - ms-discovery
  container_name: ms-routing
   - ms-config:ms-config
   - ms-discovery:ms-discovery
   - ../../ms-routing/src/main/docker:/usr/local/share/hml
   - "9090:9090"
  entrypoint: /usr/local/share/hml/
  hostname: ms-routing

The fragment above comes from the docker-compose.yml file, the one which describes the docker containers chain. Here we spin on a docker container running the Alpine Linux distribution with Java 8. On the top of it  we run a Tomcat 8 embedded servlet engine which, in turn, will run our Spring Boot microservice. By simply annotating this service with the @EnableZuulProxy annotation, this service becomes our service gateway.

The container has the name of ms-routing and depends, of course, of the config and discovery services. It mounts a writable volume and listens of the 9090 TCP port number. It defines environment variables such that to identify the config server and the discovery server and, upon start-up, it runs the script which code follows:

echo "********************************************************"
echo "Waiting for the configuration server to start on port $CONFIGSERVER_PORT"
echo "********************************************************"
while ! `nc -z ms-config $CONFIGSERVER_PORT `; do sleep 3; done
echo ">>>>>>>>>>>> Configuration Server has started"

echo "********************************************************"
echo "Waiting for the discovery server to start on port $DISCOVERY_PORT"
echo "********************************************************"
while ! `nc -z ms-discovery $DISCOVERY_PORT `; do sleep 3; done
echo ">>>>>>>>>>>> Discovery Server has started "

echo "********************************************************"
echo "Starting Routing Service with config on $CONFIGSERVER_URI"
echo "********************************************************"
java -Dserver.port=$SERVER_PORT$CONFIGSERVER_URI -Deureka.client.serviceUrl.defaultZone=$DISCOVERYSERVER_URI$PROFILE$CONFIGSERVER_LABEL -jar /usr/local/share/hml/ms-routing.jar

As we can see, before it starts the gateway service is waiting for the configuration service and the discovery service to start. The Zuul gateway may be used without the the Eureka discovery service but, in this case, the architecture is less flexible. Here is the configuration of the Zuul gateway (bootstrap.yml):

   name: hml-routing

The Zuul gateway service is configured such that to interact with the Eureka discovery service in order to have the microservices instances access details.

The only thing that we still have to do is to modify our test consumer such that to call the gateway service instead of the discovery one, as shown below:

ResponseEntity resp = restTemplate.postForEntity("http://hml-routing/hml-core/api/subscribe/", request, Void.class);
assertEquals(resp.getStatusCode(), HttpStatus.ACCEPTED);
HttpEntity<HmlEvent> request2 = new HttpEntity<>(new HmlEvent("subscriptionName", "messageId", "payload"));
HmlEvent hmle = restTemplate.postForObject("http://hml-routing/hml-core/api/publish/", request2, HmlEvent.class);
assertThat(hmle, notNullValue());
assertEquals(hmle.getMessageId(), "messageId");
assertEquals(hmle.getPayload(), "payload");

Here the new URL that the consumer uses is based on the Zuul gateway URI (hml-routing), that the discovery service assign to it, followed by the generic URI of the sample microservice, assigned also by the discovery service. At the runtime, the Zuul gateway service is responsible of chosing the effective instance that will be called in order to satisfy the request. Please compare the resulting URL with the one used in Part 3 and 4.

In order to build and run the whole stuff you need to proceed as you already did previously. First clone the GIT repository, as follows:

mkdir ms-core-config-discovery-resilience-routing
cd ms-core-config-discovery-resilience-routing
git clone
git checkout routing

Then build the project:

mvn -DskipTests clean install

Run the docker containers:

docker-compose -f docker/common/docker-compose.yml up

and run the test:


mvn --pl ms-core test

Congratulations, just by running this simple docker-compose command, you got a very complex environment, running six docker containers, each one hosting a full Linux OS. Enjoy !

Envoyer à un ami

* champs obligatoires

* champs obligatoires

« Les informations recueillies font l’objet d’un traitement informatique destiné au traitement de votre demande. Le destinataire des données est Simplex Software. Conformément à la loi « informatique et libertés » du 6 janvier 1978 modifiée en 2004, vous bénéficiez d’un droit d’accès et de rectification aux informations qui vous concernent, que vous pouvez exercer en vous adressant à Simplex Software, 26 Allée des Sapins - 95230 Soisy sous Montmorency. Vous pouvez également, pour des motifs légitimes, vous opposer au traitement des données vous concernant. »