1. Overview

Spring Cloud provides tools for developers to quickly build some of the common patterns in distributed systems (e.g. configuration management, service discovery, circuit breakers, intelligent routing, micro-proxy, control bus, one-time tokens, global locks, leadership election, distributed sessions, cluster state).

It helps manage the complexity involved in building a distributed system.

In this tutorial series, we’ll be using some of these patterns.

2. Microservices

Microservices is a software development architectural style, that decomposes the application into a collection of loosely coupled services.

It improves modularity, thus making the application easier to develop, test & deploy.

It also makes the development process more efficient by parallelizing small teams to work on different services.

There are also various difficulties regarding communication between services, managing configurations, etc in a microservice architecture.

One should go through the Twelve-Factor App Manifesto to solve many of the problems arising with a Microservice architecture.

3. Spring Cloud Config

Spring Cloud Config provides server and client-side support for externalized configuration in a distributed system.

It has two components, the Config Server & the Config Client.

The Config Server is a central place to manage external properties for applications across all environments. We could also version the configuration files using Git. It exposes REST API’s for clients to connect and get the required configuration. We can also leverage Spring Profiles to manage different configuration files for different profiles (environments).

For eg: we may decide to use an embedded H2 in our local dev profile, but use PostgreSQL in our prod profile.

The Config Client binds to the Config Server and initializes Spring Environment with remote property sources.

4. Dependencies

We’ll use Gradle to build our projects. I recommend using Spring Initializr for bootstrapping your projects.

4.1. Config Server

We’ll use:

4.2. Config Client

We’ll use:

5. Auto-Configuration

We’ll leave Spring Boot to automatically configure our application based on the dependencies added and the properties specified.

5.1. Config Server

We’ll also have to specify the Git Repository where the configurations are stored.

spring.cloud.config.server.git.uri specifies the Git Repository where the configurations are stored.

You can also pass the user credentials to access the Repository by passing the username & password. spring.cloud.config.server.git.username spring.cloud.config.server.git.password

5.2. Config Client

spring.application.name is used to fetch the correct configuration file from the Git Repository. It’s a very important property when used with Spring Cloud projects. We’ll see this later in this tutorial series.

The bootstrap properties are added with higher precedence, hence they cannot be overridden by local configuration. You can read more about it here.

management.endpoints.web.exposure.include=refresh exposes the refresh actuator endpoint. We’ll look at it in a while.

6. REST API

Let’s look at some of the REST API’s that are automatically created to manage and monitor these services.

6.1. Config Server

Let’s look at the configuration values for the application libary-service.

curl http://localhost:8888/library-service/default

The output obtained will look like this

It gives details about the Git Repository for the configuration files, the configuration values, etc. Here we can see the value for the property library.name.

6.2. Config Client

We’ll add a web endpoint that will use the property library.name defined in the configuration in the Git Repository.

A Bean marked with the annotation RefreshScope will be recreated when a configuration change occurs and a RefreshScopeRefreshedEvent is triggered.

Whenever a configuration change occurs in the Git Repository, we can trigger a RefreshScopeRefreshedEvent by hitting the Spring Boot Actuator Refresh endpoint. The refresh endpoint will have to be enabled.

management.endpoints.web.exposure.include=refresh

The cURL command for the Actuator Refresh endpoint:

curl -X POST 
  http://localhost:8080/actuator/refresh \
  -H 'content-type: application/json' \
  -d '{}'

This will update the configuration values on the Config Client.

We can now check the endpoint and verify if the new configuration value is being reflected or not.

curl http://localhost:8080/details

What if there are multiple instances of the Client running, and we want to refresh the configuration values in all of them?

This can be achieved by using Spring Cloud Bus. It links the nodes of a distributed system with a lightweight message broker. You can read more about it here.

7. Conclusion

I have tried explaining, with a simple example, how to manage externalized configurations using Spring Cloud Config. In the next tutorial, we’ll look at Service Discovery.

You can read more about:

You can find the complete example for the Config Server & Library Service on Github.