Spring Boot with Consul

Author: Shazin Sadakath

Consul from Hashicorp is a very sturdy, production ready, service registry and a configuration store. In microservices architecture this a very useful tool to register, discover and use microservices and to maintain configurations of microservices apps in a centralized manner.

In this post series I am planning to write how to integrate Spring Boot microservices with Consul starting with service registration and moving forward step by step. So let's begin.

Before we start you need to download the Consul from its official site https://www.consul.io/.

Disclaimer : I will be using development mode of Consul in this tutorial series. 

Once you downloaded the correct Consul release for your operating system, you can extract the zip file and open a command prompt/shell and navigate to the directory where consul binary is available and issue following command to check everything is fine.

consul agent -dev

If you didn't get any errors it is working fine. You can stop this for now.

Step 1 : Registering a Consul "web" service

The first step is registering a service named "web" in Consul. There are several methods to do that but I will be using the json config based method in this. To do this create a directory named "consul.d" and open a text editor of your choice and add the following json content and save as web.json inside of "consul.d" directory.

  "service": {
    "name": "web",
    "tags": [
    "port": 8080

Now after that you can start consul with this service configuration using the following command

consul agent -dev -enable-script-checks -config-dir=./consul.d

This should start Consul with the "web" service registered.

Step 2 : Writing a Spring Boot application and regisering to Consul "web" service

Create a Spring Boot application with Spring Boot Web Starter, Spring Boot Consul Configuration, Spring Boot Consul Discovery and Spring Boot Actuator. Your maven configuration file should have following dependencies more or less:








Finally you need to provide the Spring Boot Consul Instance Id as "web" in application.yml as following:


    instance_id: web


And in the main class you need to use @EnableDiscoveryClient annotation to registering your Spring Boot app in Consul as following:


public class ConsulDemoApplication {

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



Now when you run your Spring Boot Application it will by default connect to localhost port 8500 and register itself as "web" service. And consul will hit the host:port/actuator/health endpoint periodically check the status of the registered service. So if you goto host:8500 and navigate to services and select "web" service, you should see its health as below:



Now we have successfully registered a Spring Boot app in Consul as a service.


The Spring Boot source code is available at https://github.com/shazin/spring-boot-consul. In coming tutorials I will dive into more advanced features so register and follow.


You can learn more about how to get started with Consul at https://learn.hashicorp.com/consul





Tags: SpringBoot Consul Microservice ServiceDiscovery ServiceRegistry
Views: 2017
Register for more exciting articles


Please login or register to post a comment.

There are currently no comments.