Microservices with Spring Boot : Service Discovery Using HashiCorp Consul

In this article, we will implement service discovery for two microservices developed using Spring Boot that will synchronously communicate with each other using Spring's RestTemplate.

A microservice needs to know the location (IP address and port) of every service it communicates with. If we don’t employ a Service Discovery mechanism, service locations become coupled, leading to a system that’s difficult to maintain. We could wire the locations or inject them via configuration in a traditional application, but it isn’t recommended in a modern cloud-based application of this kind.

The Service Discovery mechanism helps us know where each instance is located. In this way, a Service Discovery component acts as a registry in which the addresses of all instances are tracked. The instances have dynamically assigned network paths. Consequently, if a client wants to request a service, it must use a Service Discovery mechanism.

We will be registering on HashiCorp Consul registry server and other microservices (discovery clients) will use it to register and discover services to call their APIs.

Let us set up the Consul Discovery Server.

  • Go to https://developer.hashicorp.com/consul/downloads

  • Based on your operating system, select the appropriate package and download the zip file. Unzip it in the desired registry.

  • The directory contains a consul.exe file.

  • Open a bash shell (or command prompt) in this directory.

consul agent -server -bootstrap-expect=1 -data-dir=consul-data -ui -bind=192.161.2.3

To check for your IPv4 address, run the following command

ipconfig

The consul server will by default start on port 8500 by default. Go to

http://localhost:8500/ui

You can see the dashboard there.

Build the user service

Go to start.spring.io

Note: For this article, we will use maven.

Add the following dependencies :

  • Spring Web

  • Lombok

  • Spring Data JPA

  • H2 Database

  • Spring Boot Actuator

  • Consul Discovery

For this article, we are using Spring Boot version 2.7.9 and Java 11.

Click on Generate and open the project in an IDE (IntelliJ, Eclipse, VSCode, etc)

Create a User Entity

Create an entities package and inside it create a User.java class

User.java

import lombok.*;

import javax.persistence.*;

@Entity
@Getter
@Setter
@ToString
@AllArgsConstructor
@NoArgsConstructor
@Builder
@Table(name = "users")
public class User
{
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    long id;
    String firstName;
    String lastName;
    String email;
}

Create a JPA Repository for User

Create a package named repositories and create an interface for the user JPA repository.

UserRepository.java

import com.umang345.consul.userservice.entities.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

Add database properties and discovery client configuration in the application.yml file

Add H2 Database properties, server port and discovery client configuration in the application.yml file

user-service/application.yml

server:
  port: 8081
spring:
  application:
    name: USER-SERVICE
  cloud:
    consul:
      discovery:
        healthCheckPath: /actuator/health
  datasource:
    url: "jdbc:h2:mem:testdb"
    driverClassName: org.h2.Driver
    username: sa
    password: password
    jpa:
      database-platform: org.hibernate.dialect.H2Dialect
    h2:
      console:
        enabled: true
        path: /h2

management:
  security:
    enabled: false

Create custom exception

We will create a ResourceNotFoundException to deal with situations when the user that is requested is not present in the database.

We will create our exception classes in our exceptions package

user-service/ResourceNotFoundException.java

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ResponseStatus;

@ResponseStatus(value = HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends Exception
{
    public ResourceNotFoundException(String message){
        super(message);
    }

    public ResourceNotFoundException(){
        super("The requested resource could not be found");
    }
}

Create a custom error message

To handle the exception globally we will define a custom error message in our exceptions package.

user-service/ErrorMessage.java

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Getter;
import lombok.Setter;

@AllArgsConstructor
@Getter
@Setter
@Builder
public class ErrorMessage
{
    private String message;
    private String details;
}

Create a global exception handler

We will implement a global exception handler class that will handle our ResourceNotFoundException and also any generic exception.

user-service/GlobalExceptionHandler.java

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.context.request.WebRequest;

@ControllerAdvice
public class GlobalExceptionHandler
{

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<?> resourceNotFoundExceptionHandler(ResourceNotFoundException ex, WebRequest request){
        ErrorMessage errorMessage = ErrorMessage
                                       .builder()
                                       .message(ex.getMessage())
                                       .details(request.getDescription(false))
                                       .build();
        return new ResponseEntity<>(errorMessage, HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<?> globalExceptionHandler(Exception ex, WebRequest request){
        ErrorMessage errorMessage = ErrorMessage
                .builder()
                .message(ex.getMessage())
                .details(request.getDescription(false))
                .build();
        return new ResponseEntity<>(errorMessage, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

Define the methods in the UserService interface

We will create a service layer over the JPA layer. Create a service package and add a UserService interface.

user-service/UserService.java

import com.umang345.consul.userservice.entities.User;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public interface UserService
{
    User createUser(User newUser);

    User getUserById(long userId);

    User updateUser(User user, long userId);

    List<User> getAllUser();

    void deleteUser(long userId);
}

Implement the UserService interface

We will add an implementation for the UserService interface.

user-service/UserServiceImpl.java

import com.umang345.consul.userservice.entities.User;
import com.umang345.consul.userservice.exceptions.ResourceNotFoundException;
import com.umang345.consul.userservice.repositories.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserRepository userRepository;

    @Override
    public User createUser(User newUser) {
        User savedUser = userRepository.save(newUser);
        return savedUser;
    }

    @Override
    public User getUserById(long userId)  {
        User fetchedUser = null;
        try {
            fetchedUser = userRepository.findById(userId)
                    .orElseThrow(() -> new ResourceNotFoundException("User not found with id : "+userId));
        } catch (ResourceNotFoundException e) {
            e.printStackTrace();
        }
        return fetchedUser;
    }

    @Override
    public User updateUser(User user, long userId) {
        User currentUser = null;
        try {
            currentUser = userRepository.findById(userId)
                    .orElseThrow(() -> new ResourceNotFoundException("User not found with id : "+userId));
            currentUser.setFirstName(user.getFirstName());
            currentUser.setLastName(user.getLastName());
            currentUser.setEmail(user.getEmail());

        } catch (ResourceNotFoundException e) {
            e.printStackTrace();
            return null;
        }

        User updateUser = userRepository.save(currentUser);
        return updateUser;
    }

    @Override
    public List<User> getAllUser() {
        List<User> users = userRepository.findAll();
        return users;
    }

    @Override
    public void deleteUser(long userId) {
        User currentUser = null;
        try {
            currentUser = userRepository.findById(userId)
                    .orElseThrow(() -> new ResourceNotFoundException("User not found with id : "+userId));
        } catch (ResourceNotFoundException e) {
            e.printStackTrace();
        }

        userRepository.delete(currentUser);
    }
}

Add the Controller for the User

We will implement a UserController that will expose the endpoints for the CRUD operations.

user-service/UserController.java

package com.umang345.consul.userservice.controller;

import com.umang345.consul.userservice.entities.User;
import com.umang345.consul.userservice.services.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

@RestController
@RequestMapping("/users")
public class UserController
{
    @Autowired
    private UserService userService;

    @GetMapping("/{userId}")
    public ResponseEntity<?> getUserById(@PathVariable Long userId)
    {
        User user = userService.getUserById(userId);
        Map<String, Object> response = new HashMap<>();
        if(user==null){
            User nullUser = User.builder().id(0).firstName(null).lastName(null).email(null).build();
            response.put("status", HttpStatus.NOT_FOUND.value());
            response.put("data", nullUser);
            return ResponseEntity.status(HttpStatus.OK).body(response);
        }
        response.put("status", HttpStatus.OK.value());
        response.put("data", user);
        return ResponseEntity.ok().body(response);
    }

    @GetMapping
    public ResponseEntity<?> getAllUsers(){
        List<User> users = userService.getAllUser();
        Map<String, Object> response = new HashMap<>();
        response.put("status", HttpStatus.OK.value());
        response.put("data", users);
        return ResponseEntity.ok().body(response);
    }

    @PostMapping
    public ResponseEntity<?> createUser(@RequestBody User newUser) {
        User createdUser = userService.createUser(newUser);
        Map<String, Object> response = new HashMap<>();
        response.put("status", HttpStatus.CREATED.value());
        response.put("data", createdUser);
        return ResponseEntity.ok().body(response);
    }

    @PutMapping("/{userId}")
    public ResponseEntity<?> updateUser(@RequestBody User user, @PathVariable Long userId){

        User updateUser = userService.updateUser(user,userId);
        Map<String, Object> response = new HashMap<>();
        if(updateUser==null){
            User nullUser = User.builder().id(0).firstName(null).lastName(null).email(null).build();
            response.put("status", HttpStatus.NOT_FOUND.value());
            response.put("data", nullUser);
            return ResponseEntity.status(HttpStatus.OK).body(response);
        }
        response.put("status", HttpStatus.OK.value());
        response.put("data", updateUser);
        return ResponseEntity.ok().body(response);
    }

    @DeleteMapping("/{userId}")
    public ResponseEntity<?> deleteUser(@PathVariable Long userId)
    {
         userService.deleteUser(userId);
         return ResponseEntity.ok().body("User deleted successfully with Id : "+userId);
    }
}

pom.xml

The pom.xml for the user service must contain the following dependencies :

user-service/pom.xml

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-consul-discovery</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

Add the @ EnableDiscoveryClient annotation

Add the @ EnableDiscoveryClient annotation in the UserServiceApplication.java class.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient
public class UserServiceApplication {

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

}

With this, we complete our user service.

Build the Runner Service

Now we will build the runner service that is directly called by the client.

Go to https://start.spring.io/

Add the following dependencies :

  • Spring Web

  • Lombok

  • Spring Boot Actuator

  • Consul Discovery

For this article, we are using Spring Boot version 2.7.9 and Java 11.

Click on Generate and open the project in an IDE (IntelliJ, Eclipse, VSCode, etc)

Create the User entity

We will create the same user entity for the runner class by adding the database properties.

runner-service/User.java

@Getter
@Setter
@ToString
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class User
{
    long id;
    String firstName;
    String lastName;
    String email;
}

Add a Bean for the RestTemplate

We will create a separate configuration class and add a Bean for the RestTemplate there.

MyConfiguration.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class MyConfiguration
{
    @Bean
    @LoadBalanced
    public RestTemplate getRestTemplate() {
        return new RestTemplate();
    }
}

Note: Make sure you add the @ LoadBalanced annotation to the RestTemplate Bean

Add discovery client configuration in the application.yml file

Add the server port and discovery client configuration in the application.yml file

user-service/application.yml

server:
  port: 8080

spring:
  application:
    name: RUNNER-SERVICE
  cloud:
    consul:
      discovery:
        healthCheckPath: /actuator/health


management:
  security:
    enabled: false

pom.xml

pom.xml of the runner service should contain the following dependencies.

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-consul-discovery</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

Add the Controller for the Runner Service

We will add the RunnerController that shall contain the endpoints for the client to call and the methods shall make a synchronous call to the user service to get the data.

RunnerController.java

import com.umang345.consul.runnerservice.entities.User;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.client.RestTemplate;

import java.util.Map;

@RestController
@RequestMapping("/simulate/users")
public class RunnerController
{
    @Autowired
    private RestTemplate restTemplate;

    @GetMapping
    public ResponseEntity<?> getAllUsers(){
        ResponseEntity<Map> response = restTemplate.exchange("http://localhost:8081/users",HttpMethod.GET,new HttpEntity<>(new HttpHeaders()),Map.class);
        return ResponseEntity.ok().body(response.getBody().get("data"));
    }

    @GetMapping("/{userId}")
    public ResponseEntity<?> getUserById(@PathVariable Long userId) {

        ResponseEntity<Map> response = null;
        try {
            response = restTemplate.exchange("http://localhost:8081/users/"+userId,HttpMethod.GET,new HttpEntity<Map>(new HttpHeaders()), Map.class);
            Map<String,Object> res = response.getBody();
            if((Integer)res.get("status") != HttpStatus.OK.value())
            {
                 throw new Exception("User not found with Id : "+userId);
            }

            return ResponseEntity.status(HttpStatus.OK).body(res.get("data"));
        }
        catch (Exception e){
            return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
        }
    }

    @PostMapping
    public ResponseEntity<?> createUser(@RequestBody User newUser){
        ResponseEntity<Map> response = null;
        try {
            response = restTemplate.exchange("http://localhost:8081/users",HttpMethod.POST,new HttpEntity<>(newUser),Map.class);

            Map<String,Object> res = response.getBody();
            if((Integer)res.get("status") != HttpStatus.CREATED.value())
            {
                throw new Exception("Error while creating user");
            }

            return ResponseEntity.status(HttpStatus.OK).body(res.get("data"));
        }catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(e.getMessage());
        }

    }

    @PutMapping("/{userId}")
    public ResponseEntity<?> updateUser(@RequestBody User user, @PathVariable Long userId){
        ResponseEntity<Map> response = null;
        try{
            response = restTemplate.exchange("http://localhost:8081/users/"+userId,HttpMethod.PUT,new HttpEntity<>(user),Map.class);

            Map<String,Object> res = response.getBody();
            if((Integer)res.get("status") != HttpStatus.OK.value())
            {
                throw new Exception("User not found with Id : "+userId);
            }

            return ResponseEntity.status(HttpStatus.OK).body(res.get("data"));
        }catch (Exception e){
            return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
        }

    }

    @DeleteMapping("/{userId}")
    public ResponseEntity<?> deleteUser(@PathVariable Long userId)
    {
         try {
             ResponseEntity<String> response = restTemplate.exchange("http://localhost:8081/users/"+userId, HttpMethod.DELETE, new HttpEntity<User>(new HttpHeaders()), String.class);

             return ResponseEntity.status(HttpStatus.OK).body("User deleted successfully with id : "+userId);
         }catch (Exception e) {
             return ResponseEntity.status(HttpStatus.NOT_FOUND).body("User not found with Id : "+userId);
         }
    }
}

In this case, the IP address and port of USER-SERVICE are hard-coded, we would replace it with the name of the USER SERVICE which would then dynamically be mapped from the consul server.

RunnerController.java

import com.umang345.servicediscoveryeureka.runnerservice.entities.User;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.client.RestTemplate;

import java.util.Map;

@RestController
@RequestMapping("/simulate/users")
public class RunnerController
{
    @Autowired
    private RestTemplate restTemplate;

    @GetMapping
    public ResponseEntity<?> getAllUsers(){
        ResponseEntity<Map> response = restTemplate.exchange("http://USER-SERVICE/users",HttpMethod.GET,new HttpEntity<>(new HttpHeaders()),Map.class);
        return ResponseEntity.ok().body(response.getBody().get("data"));
    }

    @GetMapping("/{userId}")
    public ResponseEntity<?> getUserById(@PathVariable Long userId) {

        ResponseEntity<Map> response = null;
        try {
            response = restTemplate.exchange("http://USER-SERVICE/users/"+userId,HttpMethod.GET,new HttpEntity<Map>(new HttpHeaders()), Map.class);
            Map<String,Object> res = response.getBody();
            if((Integer)res.get("status") != HttpStatus.OK.value())
            {
                 throw new Exception("User not found with Id : "+userId);
            }

            return ResponseEntity.status(HttpStatus.OK).body(res.get("data"));
        }
        catch (Exception e){
            return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
        }
    }

    @PostMapping
    public ResponseEntity<?> createUser(@RequestBody User newUser){
        ResponseEntity<Map> response = null;
        try {
            response = restTemplate.exchange("http://USER-SERVICE/users",HttpMethod.POST,new HttpEntity<>(newUser),Map.class);

            Map<String,Object> res = response.getBody();
            if((Integer)res.get("status") != HttpStatus.CREATED.value())
            {
                throw new Exception("Error while creating user");
            }

            return ResponseEntity.status(HttpStatus.OK).body(res.get("data"));
        }catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(e.getMessage());
        }

    }

    @PutMapping("/{userId}")
    public ResponseEntity<?> updateUser(@RequestBody User user, @PathVariable Long userId){
        ResponseEntity<Map> response = null;
        try{
            response = restTemplate.exchange("http://USER-SERVICE/users/"+userId,HttpMethod.PUT,new HttpEntity<>(user),Map.class);

            Map<String,Object> res = response.getBody();
            if((Integer)res.get("status") != HttpStatus.OK.value())
            {
                throw new Exception("User not found with Id : "+userId);
            }

            return ResponseEntity.status(HttpStatus.OK).body(res.get("data"));
        }catch (Exception e){
            return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
        }

    }

    @DeleteMapping("/{userId}")
    public ResponseEntity<?> deleteUser(@PathVariable Long userId)
    {
         try {
             ResponseEntity<String> response = restTemplate.exchange("http://USER-SERVICE/users/"+userId, HttpMethod.DELETE, new HttpEntity<User>(new HttpHeaders()), String.class);

             return ResponseEntity.status(HttpStatus.OK).body("User deleted successfully with id : "+userId);
         }catch (Exception e) {
             return ResponseEntity.status(HttpStatus.NOT_FOUND).body("User not found with Id : "+userId);
         }
    }
}

Add the @ EnableDiscoveryClient

Add the @ EnableDiscoveryClient annotation in the RunnerServiceApplication.java class.

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

@SpringBootApplication
@EnableDiscoveryClient
public class RunnerServiceApplication {

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

}

This completes our runner service.

Note: Our runner service will run on port 8080 and user service will run on port 8081

Now let's run both services and we will see our services getting registered in the consul server.

We are using Postman for testing our services.

POST

We will create two users

{
    "firstName" : "Umang",
    "lastName" : "Agarwal",
    "email" : "ua@test.com"
},
{
    "firstName" : "John",
    "lastName" : "Doe",
    "email" : "jd@test.com"
}

GET ALL

Let's fetch all the users.

Get User By Id

Let's get the user with Id 2

PUT

Let's update the user with id 1

{
    "id": 1,
    "firstName" : "Umang",
    "lastName" : "Agarwal",
    "email" : "ua2@gmail.com"
}

Delete

Let's delete the user with id 2

We have tested all our endpoints here.

Find the source code of the project on GitHub.

Do star the repository to access the source code of all the articles.

I hope you found the article useful.

Let's connect :

Happy Coding :)