Getting Started | Service Registration and Discovery

What You Will Build

You will set up a Netflix Eureka service registry, named eureka-server, and then build two web clients, named servicea and serviceb, that both register with the Eureka server. One of the web clients, serviceb, will call the other web client, servicea, using org.springframework.cloud.client.discovery.DiscoveryClient and Spring Framework’s Rest Client.

What You Need

About 15 minutes
A favorite text editor or IDE
Java 17 or later

How to Complete This Guide

Like most Spring Getting Started guides you can start from scratch and complete each step, or you can jump straight to the solution, by viewing the code in this repository.

To see the end result in your local environment, you can do one of the following:

Download and unzip the source repository for this guide
Clone the repository using Git: git clone https://github.com/spring-guides/gs-service-registration-and-discovery.git
Fork the repository which lets you request changes to this guide through submission of a pull request

Starting with Spring Initializr

For all Spring applications, you should start with the Spring Initializr. The Initializr offers a fast way to pull in all the dependencies you need for an application and does a lot of the set up for you.

This guide needs three applications. The first application (the server application) needs only the Eureka Server dependency. The second and third applications (the client applications) need the Eureka Discovery Client and Spring Web dependencies.

You can use the following links for pre-initialized projects from Spring Initializr:

Due to the number of services in this guide, only the solutions are provided in the GitHub repository. To start from scratch, generate the blank projects using the links above or using Spring Initializr, as defined below.

To manually initialize the Eureka Server project:

Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.
Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Maven and Java.
Click Dependencies and select Eureka Server for the server application.
Click Generate.
Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.

To manually initialize the Service A and Service B projects:

Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.
Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Maven and Java.
Select Eureka Discovery Client and Spring Web for the client applications.
Click Generate.
Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.

If your IDE has the Spring Initializr integration, you can complete this process from your IDE.

Start a Eureka Service Registry

You first need a Eureka Server. You can use Spring Cloud’s @EnableEurekaServer to stand up a registry with which other applications can communicate. This is a regular Spring Boot application with one annotation (@EnableEurekaServer) added to enable the service registry. The following listing (from eureka-server/src/main/java/com/example/eurekaserver/EurekaServerApplication.java) shows the server application:

package com.example.eurekaserver;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer;

@SpringBootApplication
@EnableEurekaServer
public class EurekaServerApplication {

	public static void main(String[] args) {
		SpringApplication.run(EurekaServerApplication.class, args);
	}

}

In a production environment, you likely want more than one instance of the registry. You can find additional information about configuring the Eureka Server here.

By default, the registry also tries to register itself, so you need to disable that behavior. Additionally, it is a good convention to put this registry on a separate port when using it locally.

Add some properties to eureka-server/src/main/resources/application.yml to handle these requirements, as the following listing shows:

spring:
  application:
    name: eureka-server
server:
  port: 8761
eureka:
  client:
    register-with-eureka: false
    fetch-registry: false
logging:
  level:
    com.netflix.eureka: OFF
    com.netflix.discovery: OFF

You can now start the Eureka server by running ./mvnw spring-boot:run.

Talking to the Registry

Now that you have started a service registry, you can stand up clients that interact with the registry. Our client applications, ServiceA and ServiceB, automatically register with the Eureka server because we have spring-cloud-starter-netflix-eureka-client on the classpath. To avoid port conflicts, set the server.port parameter in both ServiceA and ServiceB:

Service A:

spring:
  application:
    name: servicea
server:
  port: 8081

Service B:

spring:
  application:
    name: serviceb
server:
  port: 8082

At this point you, should be able to run all three applications. You can use the IDE or execute the ./mvnw spring-boot:run command from each application folder.

When the applications run, you can view the Eureka dashboard.

Service A Endpoint

Create a new class called com/example/servicea/controller/ServiceARestController.java in the servicea project to expose an endpoint you can use to test the application.

package com.example.servicea.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ServiceARestController {

	@GetMapping("/helloWorld")
	public String helloWorld() {
		return "Hello world from Service A!";
	}

}

Service B Endpoint

Create a new class called com/example/serviceb/controller/ServiceBRestController.java in the serviceb project to expose an endpoint that calls servicea.

package com.example.serviceb.controller;

import org.springframework.cloud.client.ServiceInstance;
import org.springframework.cloud.client.discovery.DiscoveryClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestClient;

@RestController
public class ServiceBRestController {

	private final DiscoveryClient discoveryClient;
	private final RestClient restClient;

	public ServiceBRestController(DiscoveryClient discoveryClient, RestClient.Builder restClientBuilder) {
		this.discoveryClient = discoveryClient;
		restClient = restClientBuilder.build();
	}

	@GetMapping("helloEureka")
	public String helloWorld() {
		ServiceInstance serviceInstance = discoveryClient.getInstances("servicea").get(0);
		String serviceAResponse = restClient.get()
				.uri(serviceInstance.getUri() + "/helloWorld")
				.retrieve()
				.body(String.class);
		return serviceAResponse;
	}
}

This class uses a DiscoveryClient to find the serviceId of servicea based only on the application name. This guide has only one instance of servicea, so we can look only at the first instance. This is seen in the following line:

ServiceInstance serviceInstance = discoveryClient.getInstances("servicea").get(0);

Once you have a ServiceInstance that refers to the location of servicea, you can now use the information in Spring Framework’s Rest Client.

... = restClient.get().uri(serviceInstance.getUri() + "/helloWorld")...

You can test all three applications by running the following command:

curl http://localhost:8082/helloEureka

And you should see the result:

Hello world from Service A!

Test the Application

This guide walked through the following steps (which you could do by implementing the code shown throughout this guide or by using the code in the solution repository):

Run eureka-server with the ./mvnw spring-boot:run command from the eureka-server folder
Run servicea with the ./mvnw spring-boot:run command from the servicea folder
Run serviceb with the ./mvnw spring-boot:run command from the serviceb folder
Observe that servicea and serviceb are registered by viewing the Eureka Dahsboard at http://localhost:8761/
Run the curl http://localhost:8082/helloEureka command to test all three applications are working properly
Observe the output, Hello world from Service A!

There is a short delay while servicea and serviceb register themselves and refresh the instances from the registry. If the curl command initially fails, wait a minute and try again.

Summary

Congratulations! You have just used Spring to stand up a Netflix Eureka service registry and to use that registry in a client application.

Service Registration and Discovery