DEV Community

Cover image for Spring Cloud Config Server: Step by Step
Mark Dsouza
Mark Dsouza

Posted on

Spring Cloud Config Server: Step by Step

Spring Cloud Config Server is used to provide server-side and client-side support for externalized configuration in a distributed system. So when you have multiple microservices, and you want to easily control the configuration for all of them at one go - you'll mostly be looking at Spring Cloud Config Server.

So how do we do this?

We will create a git project which contains all your properties files for the multiple microservices that you have (easy enough). We then create one spring boot application whose only role will be to be a micro service pointing to these files as it acts as a Spring Cloud Config Server. All the other microservices(the clients) can be configured to get the required properties from the Config Server.

This isn't too tricky, and is actually easy to implement. In the below steps, I will walk you through how you can set this up in your project and even configure profiles for your microservices.

Step 1) Create the Spring Cloud Config Server

1.1) Create a Sprig Boot App

Lets start off creating our Spring boot application using
I am using the Spring boot version 2.4.3
Make sure the dependency is Config Server and not Config Client.
Hit generate and you're done.

1.2 Update the Main Class

Open the project with your IDE.
Open up your main Spring boot class with @SpringBootApplication and add @EnableConfigServer as well (Imported from import

1.3 Create a git repo with the properties file

Create a new folder where you will hold your config file and do a git init on that folder.

mkdir config-files
cd config-files
git init
Enter fullscreen mode Exit fullscreen mode

now create the property file that you will map to your config server. We will be naming our microservice : microservice-one
File Name :

Enter fullscreen mode Exit fullscreen mode

Now add and commit your changes. Else the spring boot app will not read it

git add .
git commit -m "created property file for microservice-one"
Enter fullscreen mode Exit fullscreen mode

Note: you can also use yml files here

1.4 Update

Copy the path of your new git repository and paste it in your file. = spring-cloud-config-server
server.port=8888 = file:///c:/Users/madsouza/Desktop/blogPost/config-files
Enter fullscreen mode Exit fullscreen mode

The config server is generally set to port 8888.
Windows users should make sure you are using the / and not \ when copying the path.

1.5 Test it out

Launch the application and navigate to : http://localhost:8888/microservice-one/default
where microservice-one is the name of the file we have created.
localhost 8888
As you can see, the property you have mapped is present. With this we are done setting up our basic Spring Cloud Config Server

Step 2) Create the Client Microservice

Next up is fetching the property from this config server in an independent microservice. In our case microservice-one

2.1 Create a Spring Boot App

Back to with Spring boot version 2.4.3
Go ahead and generate the app.

2.2 Update

Open the app with your IDE and its time to do some configuration = microservice-one
spring.config.import = optional:configserver:http://localhost:8888
#backup value
Enter fullscreen mode Exit fullscreen mode

Here, we are basically importing the config server and providing the URL for the microservice.
We can also mention the backup value in case for some reason we cannot find the config server.

2.3 Create a configuration class

Let us now create a Class that can read the properties from the config server



public class Configuration {
    private String value;

    public String getValue() {
        return value;

    public void setValue(String value) {
        this.value = value;
Enter fullscreen mode Exit fullscreen mode

Here we are setting the Configuration Properties annotation with the name of the file. This Class will automatically get set when the spring boot application is run and it would set the value that is present in the Spring Cloud Config Server

2.4 Create a Rest controller

Now lets expose an endpoint which returns the config value


import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

public class MicroServiceController {

    Configuration configuration;

    public String retrieveLimits(){
        return configuration.getValue();
Enter fullscreen mode Exit fullscreen mode

Here we are auto-wiring the configuration class we created in the previous step and setting it at the '/endpoint' endpoint.

2.5 Test it out !

Run the microservice-one spring boot application. and go to the defined controller end point

controller end point

With these simple steps you are DONE!
I hope it doesn't seem as challenging as you thought it would be !!

Step 3) Implementing Profiles

Now the only way to enhance this and make it really useful is having using different profiles. Depending on the environment, we usually have different properties file being used. So let's see how we can add different profile related configuration to our server and have it reflected in our client

3.1) Commit additional properties files in git

Now create additional files. One for dev and one for qa.
File Name:

Enter fullscreen mode Exit fullscreen mode

File Name:

Enter fullscreen mode Exit fullscreen mode

make sure you do a git add and commit

git add .
git commit -m "created additional dev qa property files"
Enter fullscreen mode Exit fullscreen mode

That's all you need to add new properties files. You don't need to touch the spring boot application we created as such. Just check in the files created.

3.2) Test the profile related server endpoints

Earlier we navigated to
Now, 2 new endpoints open up in our 8888 port.

dev endpoint

qa endpoint
Note that for both of these, we actually see the default value available as well.

3.3) Update the micro service

All you really need to do is update the file of microservice-one and set the profile you want to use
The overall file would now look like = microservice-one
spring.config.import = optional:configserver:http://localhost:8888

#backup value
Enter fullscreen mode Exit fullscreen mode

3.4) One last Test

Now if we hit the same endpoint we did earlier : http://localhost:8080/endpoint
dev value

How quick and easy was that? You can very easily set it up for other profiles as well. I hope you've found this useful!!

Top comments (13)

hendisantika profile image
Hendi Santika

Now I have errors again. As follow:
It is said: 422 Unprocessable Entity

2021-05-09 10:08:11.007 WARN 28080 --- [nio-8888-exec-1] .m.m.a.ExceptionHandlerExceptionResolver : Resolved [ Cannot clone or checkout repository:]

But, When I change config from to${user.home}/Desktop/tes/configuration

it works.

Then If I change properties file to yml it error again.

Any suggestion?


markbdsouza profile image
Mark Dsouza

Hey Hendi, Can you try adding a .git to the end of your uri property?

hendisantika profile image
Hendi Santika

If I am using git it show error. I will show you the link.
This is my repository to implement micro service with Spring Cloud.

Here's the link --> You can try it on your local.


Thread Thread
hendisantika profile image
Hendi Santika

I will add you to my gitlab group so that You can clone.
May I know your gitlab account?


Thread Thread
markbdsouza profile image
Mark Dsouza

Thanks tried setting it up on my local and Your yml files seem to be causing the issue. Im not sure how you got it working on your local.
Below would be my suggestion to resolve this
1) Keep either the .properties or .yml file. Don't keep both
2) Use to check your yml file. The way you have tried to define your profiles wont work here. Try just 1 default profiles to start off and get it running
3) Initially point it to your local copy of your git repo only having bank-account-service.yml . Access localhost:8888/bank-account-service/default . Only if you see the results here move ahead.
4) Once everything is 100% alright on local, Push your git repo to remote and change the url.
5) To implement profiles the file name needs to change.. in your case bank-account-service-dev.yml
Let me know you need more help :)

Thread Thread
hendisantika profile image
Hendi Santika

Hi Mark,

  1. I was trying to use yml file only but it fails. Then I try to use properties file its working fine.
  2. I was check using it is said valid.
  3. I don't know it's not coming the result.
  4. Still error on my local. I already pushed new file.
  5. Previously I tried like that but still error. Now I am rolling back to use bank-account-service-dev.yml & bank-account-service-uat.yml but still error.

Cannot pull from remote, the working tree is not clean.

Thread Thread
markbdsouza profile image
Mark Dsouza

Hmm any changes to your git repo containing these files, make sure you do a git add and git commit and then restart your cloud config server for it to reflect properly
Also one other thing with the yml file is you don't need the
on-profile: dev
if you follow the naming convention.
All you need to do is set the profile for the microservice of the bank-account-service when you run it.

Thread Thread
hendisantika profile image
Hendi Santika

It's working now. I am using Spring Cloud Native with File Backend.
Git Backend is to much error for me.

Thank for your support.

Thread Thread
markbdsouza profile image
Mark Dsouza

Awesome !

anuradha151 profile image
Anuradha Ranasinghe

This works for gitlab uri. Why doesn't need this for github uri.

Thread Thread
markbdsouza profile image
Mark Dsouza

Sorry anuradha. I didn't get your question.
Are you facing any issues with the tutorial?

braians profile image
Braian Silva

I forgot to put dependency "Config Client" in my service but now work very well, great article. Thanks

maxmengtor profile image

this is the best for scc server setup