Now-a-days we often come across the word ‘Microservices’ while discussing any new java based server side

development (mainly service API). Microservices approach now has become an industry standard for any new API
development and almost all the organization is promoting this. Today we will discuss and do some demo on a
specific Microservice feature called Config Server. It is like externalizing properties/resource file out of project
code base to an external service altogether, so that any changes to that property does not have any impact in the
actual service which is using that – no code change and no deployment – so the approach is very much justifiable.

Where it comes from

The idea has come from the original 12 factor app[https://12factor.net/config] manifesto related to modern cloud
native approach of application development. As per the 12-factor app manifesto, it is suggesting to keep
properties/resources in the environment where the values of those resources vary during run time.

As an example, let’s say one service is dependent on another service [invoked for certain business scenario] and if
that dependent service URL got changed to some other service, and then usually we need to build and deploy our
service with the updated location is required. Now if we go by 12 factor app suggestion and if we read those config
from external service deployed as different process, then we just need to refresh that config server.

So, the idea is very clear and effective. Let’s now see how we can achieve this.

Steps to achieve this

We will do this using spring-boot based Spring-cloud api that is available and very popular. Also, we will use both
local and git configuration to place the properties file.

So finally, our technology stack for this poc will be

1. Java 1.8
2. Spring cloud
3. Spring boot
4. Spring rest
5. GitHub as resource repository.
6. Maven
7. Eclipse IDE
8. Unrestricted internet connectivity for maven download.

To start with we will develop two microservices using spring boot,

1. one is the config server, providing the configuration in runtime
2. one is the config client service, using the configuration exposed as config server.

Config Server – server side configuration:

Let’s first build the config server part. For that we will do the below steps
 Generate the project structure - Start with spring initializer portal[https://start.spring.io] which is a great
starting point for creating any spring boot based application. Here we will choose only config-server starter
pom. The screen shot is something like this. With this configuration, once we generate the project, one zip
file with the artifact id we will be downloaded, which we will simply import in eclipse after unzipping.
 Import the project in Eclipse – Once you have the zip file from the spring initializer side, we need to unzip
it to a directory and import it to eclipse as maven project
 Build in eclipse – Next step will be to run mvn clean install from either command prompt or from eclipse
whatever you are comfortable with. In this step, all necessary dependencies will be downloaded from
maven repo. Make sure you are trying it from any network where no download restriction is present.
Successful build in this step is very much required to proceed to the next steps.
 Add Config Server Annotation - Now open the Spring Application class that spring already has provided
and add the @EnableConfigServer
[org.springframework.cloud.config.server.EnableConfigServer ] annotation before the class and
build the project once again. With this annotation, this artifact will act like a spring config server.
After adding this annotation the class will look like below – the class name can be different depending om
the Project name you gave giving while generating, also you can manually change the class name to a
name you like it.

package com.howtodoinjava.example.springconfigserver;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.config.server.EnableConfigServer;

@EnableConfigServer
@SpringBootApplication
public class SpringConfigServerApplication {

public static void main(String[] args) {

SpringApplication.run(SpringConfigServerApplication.class, args);
}
}

 Create the Git repository – Next very important step is to create a local git repository. We can easily be
converted to a remote repository later by configuring it’s URL in the properties file. We will place the
external property file [configuration], that will be used by the Config server microservice to provide the
external configuration of properties. We need to follow the below steps to create a local git repository and
check in a sample properties file.
1. Make sure you have git shell installed in your machine and you can run git bash from
command prompt. To verify it open command prompt and type git, if it recognize then you
probably have the git prompt installed, if not please follow git website, download and install
as per the instruction.
2. Now Create a directory ‘config-server-repo’ in your Desktop.
3. Then create a file config-server-client.properties file in the config-server-repo directory and
add the message there msg = Hello world - this is from config server.
4. Then create another file config-server-client-development.properties file in the config-server-
repo directory and add the message there msg = Hello world - this is from config server –
Development environment.
5. Then create another file config-server-client-production.properties file in the config-server-
repo directory and add the message there msg = Hello world - this is from config server –
Production environment.
6. Here we are maintaining same properties for different environment, as we generally maintain
properties for different environments like url/credentials, Database details etc. Here the most
important point is that we need to append hyphen (-) with the environment name in each
property so that config server understands it. Also, we need to name the properties file with
the config client service name that we will create after this.
7. Now open command prompt from ‘config-server-repo’ directory and run command git init to
make that directory as git repository
8. Now run git add . to add everything to this repo.
9. Then finally we need to commit the properties file by running command git commit –m “initial
checkin”. This should check in all the files in the git repository. Here is the command prompt
screen shot for the same.
 Point the git repo from Config Server – Create one file called bootstrap.properties in the
src\main\resources directory of spring-config-sever project and add below lines.

#Server port
server.port = 8888
#Git repo location.
spring.cloud.config.server.git.uri=${USERPROFILE}\\Desktop\\config-server-repo
#Disable security of the Management endpoint
management.security.enabled=false

Now let’s understand those two properties –

server.port defines the port on which the embedded server will start
 spring.cloud.config.server.git.uri will bind the git location to look for the configuration. Here we are using
local git repo but can be switched to remote got location by just changing this location.

management.security.enabled=false will disable the spring security on the management enpoints like
/env, /refresh etc. This is for development settings, in production security should be enabled.

So, this step will point to a git location and server port.

 This is very much we need to do in the config server side, not do a final clean install command on this
project so that everything gets compiled properly and packaged also in the target folder as well as in local
maven repository. We will start the config server service once we have the client part ready and we will
finally test the feature.

The command to run the service in embedded mode is

java -jar target\spring-config-server-0.0.1-SNAPSHOT.jar however we will revisit this in the testing part.

 Check if the Config-server can recognize the properties –

a. First run the config server microservice from command prompt by using the command from CMD
java -jar target\spring-config-server-0.0.1-SNAPSHOT.jar

b. Now open browser and check below Urls, it will return the JSON output and in propertySources
section we can see all the properties we have added in the properties. This ensures that config-
server is running successfully, it has recognized the git location and it is serving configuration for
different environments. Now we will proceed to the client side implementation where we will use
those properties from a separate microservice which is our final goal – to externalize the
configuration to different service.
http://localhost:8888/config-server-client/development
http://localhost:8888/config-server-client/production

c. Check if any runtime change in the property file is reflected by the server without restart – Do
any change in the value of any environment’s property and check-in that file and then run that
specific environment’s endpoint, and verify that changed value should be reflected immediately
without restarting the server – that is the magic of Spring Config Server. To do the git check in,
after doing the change and save the file by any text editor, run the command git add. And git
commit -m “test” from config-server-repo directory in the desktop. This step ensures that we
don’t need to restart the server for any configuration change for the server side.

Config Server - Client side configuration:

 Maven project generation – go to https://start.spring.io/ web portal and generate client project with the
below selected artifacts
1. Actuator
2. Config Client
3. Web
4. Rest Repositories
 The screen will look like below before generation, once we click on generate, we will get the artefactid.zip
file download option. Like Spring-Config-Server, unzip the file in some directory and import in eclipse.

 Add one RestController to view the Server side property values in the response. To do that open the
@SpringBootApplication class file that has been generated, and add the below small class in the end of
that file. This is very simple and straight forward, we are just exposing one method at /message URL where
we will just return the property value of msg that will be supplied by the config server microservice, which
is configured to a local git repository [which will be migrated to a remote git repository in production!]

package com.howtodoinjava.example.springconfigclient;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class SpringConfigClientApplication {

public static void main(String[] args) {

SpringApplication.run(SpringConfigClientApplication.class, args);
}
}

@RefreshScope
@RestController
class MessageRestController {

@Value("${msg:Hello world - Config Server is not working..pelase check}")

private String msg;
 @RequestMapping("/msg")
String getMsg() {
return this.msg;
}
}

 Bind with the config server – Create one file called bootstrap.properties in the src\main\resources
directory and add the below properties to connect with the config server along with some required
configuration.
spring.application.name=config-server-client
#Active Profile - will relate to development properties file in the server.
#If this property is absent then,default profile will be activated which is
#theh property file without any environment name at the end.
spring.profiles.active=development
# N.B. this is the default:
spring.cloud.config.uri=http://localhost:8888
management.security.enabled=false

Let’s understand the properties now.

Here spring.application.name is just the application name of the microservice that would be deployed.
spring.cloud.config.uri is the property to mention the config server url. Point to note that our config server
is running on port 8888; verify it by opening the application.properties file of the spring config server code
base and check the server.port=8888

management.security.enabled=false will disable the spring security on the management enpoints like
/env, /refresh etc. This is for development settings, in production security should be enabled.

 This is very much we need to do in the config client side, not do a final clean install command on this
project so that everything gets compiled properly and packaged also in the target folder as well as in local
maven repository. We will start the config client service along with the server side and we will finally test
the feature.

Testing

1. Build and Run Config Server first.

Open command prompt from spring-config-server folder and run clean install command. Once
build is completed run the application from that command prompt itself by java -jar command like
java -jar target\spring-config-server-0.0.1-SNAPSHOT.jar
This will start the config server service in 8888 port in localhost.
2. Build and run Config Client Project.
Similarly, Open command prompt from spring-config-client folder and run clean install command.
Once build is completed run the application from that command prompt itself by java -jar command like
java -jar target\spring-config-client-0.0.1-SNAPSHOT.jar
This will start the Config Client service in 8080 port of localhost.
3. Now in the browser open the /msg rest endpoint by browsing the url http://localhost:8080/msg it should
return Hello world - this is from config server which is mentioned in the config-server-
client-development.properties file.
 4.

5. Now we will do a property change and test if this can be reflected in the config client service without
restarting any of the microservices.
Do some change, in the value of the msg property in the config-server-client-development.properties and
check-in in the local git, then hit the http://localhost:8080/msg again in the browser, the VALUE SHOULD
BE THE OLD VALUE ONLY!!!

To reflect the new value, we need to refresh the configuration by hitting http://localhost:8080/refresh
endpoint in POST method from any of the REST client.

Once you have successfully refreshed the config client service, the new value should be reflected in the
service response. This is because, @RefreshScope annotation the RestController that we have
exposed.

Important touch base points that can create problem –

1. Property files name and the Client Module service name [ spring.application.name=config-server-
client] should be exactly same, otherwise, properties will not be detected. Actually, Config Server exposes
the properties in an end point of property file name, if you browse URL http://localhost:8888/config-server-
client/development it will return all the environment values.

2. Make sure you have checked-in the properties files in the git reop by using git init/add/commit commands as
described above.
3. Make sure you have refreshed the client service environment by invoking POST method of
http://localhost:8080/refresh by any REST client. Otherwise changed values will not be reflected in the client
service.
4. Make sure at the time of starting the client service, your server service is running, otherwise it might take
some time to register.

That’s all about this topic. Please add comments if you have able to configure all the points mentioned in this
article, we will be happy to look into the problem.

Happy Learning!!!