Registering Multiple Local Microservice Instances With Netflix Eureka

When developing Spring Boot and Spring Cloud microservices, most often we devs run them locally, also running local instances of Spring Cloud Config Server and Spring Cloud Netflix Eureka to provide essential scaffolding for our microservices-in-development and to more closely replicate our test and production environments. Many times, we simply run a single instance of a microservice under development, which works with nearly no effort on our part: provide a desired port number for the service either via internal properties (usually in the project's application.properties/.yml configuration file) or more likely, by pointing the application to our local Spring Cloud Config Server. But what happens when you want to run multiple instances of said microservice and register them with Eureka so that they're accessible to consuming microservices?

First, a bit of background for Spring Cloud Netflix Eureka. Eureka is a service registry, providing service registration and discovery functionality for many critical distributed systems around the globe. A service registry provides a way for microservices to see and be seen, where consuming microservices can easily locate "backing services" other microservices that provide capabilities the consuming services use. In an ephemeral environment, i.e. the cloud, when one microservice fails/goes offline/is unreachable, another is quickly spun up to replace it in a different location. A service registry makes it easy for microservice instances to find each other, wherever they may be at that point in time.

Now let's scope things in a bit. Running locally on our dev machine, when a microservice instance contacts Eureka wishing to register itself, Eureka combines the application's IP address with the port number on which it's listening to create a unique indentifier/locator for that microservice instance. Manually changing the designated port on which our microservice instance is going to run (if spinning up multiple instances) is tedious. Instead, we can simple designate 0 as our microservice's target port by setting server.port=0 in its properties; doing so results in Spring Boot assigning a random available port number to each instance we run.

But there is a catch. Our microservice instance attempts to register its presence with Eureka before this port assignment, resulting in a registration using the local IP address and a port number of zero (0), as does every subsequent instance of that microservice. This effectively restricts us to running a single instance of any local microservice we wish to register with a local Eureka instance. Fortunately, there is an easy fix: assign a unique instance-id, dynamically, to each of the instances for use by Eureka.

Here is a project in which I demonstrate how to accomplish this, using a Coffee Service (what else?) and the latest snapshot of Spring Cloud (currently Finchley.BUILD-SNAPSHOT). I've added the following values to the property file served to every instance of coffee-service from the Config Server:

server:  
  port: ${PORT:0}

eureka:  
  instance:
    instance-id: ${spring.application.name}:${spring.application.instance_id:${random.value}}

NOTE: I generally prefer to use YAML files for properties, but they can also be represented (in .properties files) as direct property assignments, as follows:

server.port=${PORT:0}

eureka.instance.instance-id=${spring.application.name}:${spring.application.instance_id:${random.value}}

The first line assigns to server.port the value of variable PORT (if it exists); if not, 0. This prompts Spring Boot to assign a random, unused port.

The second line appends the current spring.application.instance_id (if it exists) to the spring.application.name, separated by a colon (:). If the spring.application.instance_id doesn't exist, it instead appends a random value to create a unique Eureka instance identifier for this instance.

To start two instances of our coffee-service from IntelliJ IDEA, we must choose "Edit configurations..." from the drop down menu at the top right of our edit window:

In the "Run/Debug Configurations" window, we must de-select the checkbox for "Single instance only", as indicated in the following graphic. This will create a new instance of our microservice each time we run our application, rather than stopping the existing instance and starting it anew.

Now when we run multiple instances of our coffee-service, we see entries like these appear in our Eureka service's logs:

And here is how they are displayed in the Eureka Dashboard:

Summary

Running multiple instances of a microservice locally - and registering them with Eureka for discoverability - is pretty simple to do with only a few small configuration settings. Using a current Spring Cloud snapshot build (such as Finchley.BUILD-SNAPSHOT in these examples) and setting server.port to 0 and the microservice's eureka.instance.instance-id to a unique value-generating string allows both to be assigned dynamically and uniquely upon instance initialization. Spring Cloud Netflix Eureka handles the rest.

Click here to follow me on Twitter for more useful posts like this, to ask questions you might have, or just to say hi. Happy coding!

Code repository with full example