A guide on using HashiCorp’s consul as a KV store for a spring boot application ?

Photo by Martin Adams on Unsplash

Hi everyone, before starting the actual guide, I will give you a brief introduction about consul and consul’s KV store feature.

What is consul?

Consul is a software first released in 2014 by HashiCorp.
It is a service mesh solution that provides full featured control plane with DNS-based service discovery and distributed key-value storage, segmentation and configuration and can be used individually or together to build a full service mesh.

What is consul’s KV store ?

Consul’s KV store is one of the feature available in Consul and has the ability to store distributed Key-value.

It is mainly used for dynamic configuration, feature flagging, coordination, leader election, and also has many other uses apart from these.

Its simple HTTP API makes it easy to use and can be considered as an industry standard.

However in my guide I will explain you how to use consul’s KV store feature for dynamic configuration.

I have considered a simple spring boot application which will use spring consul to bind the consul value to the spring boot application at run time.

Prerequisite

Need to install HashiCorp consul software . For this you can follow the below steps.

1. Download consul software (https://www.consul.io/downloads)
2. Next unzip the downloaded package
3. Place the executable file (If you are installing in Windows OS) under the folder where you want to start the consul agent
4. Next start the command prompt and native to the path where consul exec is place
5. Next check if consul is available or not by typing this command.

consul

You will see the below screen if everything is fine -

6. Finally we will run consul agent by executing this command

consul agent -dev

As shown in the below screen .

Note: consul agent is only recommended for dev mode. In case you want to retain the key value pair whenever the consul starts you can run the consul agent using this command, consul agent -server -bind=127.0.0.1 -data-dir=./data -bootstrap-expect=1 -node=agent-one -ui

Once consul is install you can check it by hitting the browser with http://localhost:8500 url.

consul browser

Note: If you get any issue , please check the default port no. 8500 is available or not else you need to change the port no.

Once consul is up we need to create the consul key value pairs and folder structure. We can create KV pair using consul UI one by one or by using command prompt with file import to generate all the keys at once.

This is the command consul kv import @/your-file-path/filename.json for creating KV pair in consul.

Below is the screen -

Note: In order to create KV pairs at once using file system we must encode the value in base 64 format, otherwise we will get illegal base64 data at input byte 4 error

Below is the file that I have used -

JSON file to generate KV pair

Note: In this file we have encode the actual value in base 64 format

Below is the screen for consul folder structure after keys got generated -

Note: In case you want to create a key from consul UI you do not need to encode the value.

Also the folder name should always start with “config” name followed by application main class name as shown below -

Now let us create a step by step guide to enable consul with KV pair for a simple spring boot application.

In order enable consul we need this dependency in your build.gradle file as shown below -

Note: The spring actuator is mandatory so that consul keeps checking the health status of the spring boot application

Next , we need to create a bootstrap.properties file and configure these consul properties as shown below -

Note: The application name should match the folder name created under consul “config ”folder which is already mentioned.

Next, we need to create a ApplicationConfig class and enable @value annotation to bind the value from consul to the application as shown below -

Note : @RefreshScope annotation is used to immediately refresh the values without restarting the application when there is a change in consul’s value

Lastly, we need to add @EnableDiscoveryClient annotation to our main application as shown below -

Next, run the application, if everything is fine you can see these messages as shown below.

Application is registered with consul

Note : if the key is not configured properly in the consul or the key is changed to another name in the spring boot application , you will get this error Could not resolve placeholder ‘spring.consul.test’ in value “${spring.consul.test}”, which means from consul it not able to bind the application key.

This is how we can use consul’s KV store feature for dynamic configuration, this is mainly helpful when you want to configure value at run time.

Hope this will help my fellow developers.

Please share your feedback whoever reads this content, this will in a way encourage me.

GitHub link: https://github.com/mousumi8/spring-boot-consul/tree/master

References: https://spring.io/projects/spring-cloud-consul, https://www.hashicorp.com/products/consul