Centralized Configuration with Spring Cloud Config

The Problem: Configuration Chaos

In a monolithic application, managing configuration is relatively simple. You have a single application.properties or application.yml file. But imagine a system with 10, 50, or 100 microservices. If each service has its own configuration file, you'll quickly face significant problems:

• Duplication: Common properties, like database credentials or message broker URLs, are scattered across many services.
• Inconsistency: Updating a shared property becomes a tedious and error-prone task of finding and changing it in every single service.
• Costly Changes: Even a minor configuration change requires rebuilding, re-testing, and redeploying the affected service, which slows down development cycles.

This video provides an excellent summary of these challenges.

The Solution: Spring Cloud Config

Spring Cloud Config provides a straightforward client-server approach to solve these problems. The architecture consists of three main components:

1. Configuration Repository: A backend storage for your configuration files. This is typically a Git repository, which gives you versioning, history, and access control over your configuration changes.
2. Config Server: A Spring Boot application that connects to the Configuration Repository. It reads the property files and exposes them to other services through a REST API.
3. Config Client: Your microservice (e.g., an order service, user service) which is configured to fetch its properties from the Config Server on startup.

Let's see a more detailed architectural overview.

Now that we understand the architecture, let's build it.

Step 1: Create the Configuration Repository

The first step is to create a central place to store our configuration files. A public GitHub repository is perfect for this.

1. Navigate to GitHub and create a new public repository. Name it something like spring-cloud-config-repo.
2. Inside this new repository, create a file named greeting-service.yml. This file will contain properties for a service named greeting-service running in the default profile. Add the following content:

   message:
     greeting: "Hello from the default profile!"
   

3. Create another file named greeting-service-dev.yml. The -dev suffix ties this file to a Spring profile named dev. Add this content:

   message:
     greeting: "Hello from the development profile!"
   

4. Commit these two files to the main branch of your repository.

Your configuration is now version-controlled and ready to be served.

Step 2: Build the Spring Cloud Config Server

Next, we'll create a Spring Boot application that acts as our Config Server.

1. Go to start.spring.io.

2. Set up a new project with the following:

   • Project: Maven
   • Language: Java
   • Group: com.example
   • Artifact: config-server
   • Dependencies: Add Config Server.

3. Generate the project, download the ZIP, and open it in your IDE.

4. Open the main application class (e.g., ConfigServerApplication.java) and add the @EnableConfigServer annotation. This single annotation transforms your application into a Config Server.

   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   import org.springframework.cloud.config.server.EnableConfigServer;
   
   @SpringBootApplication
   @EnableConfigServer // This enables the Config Server
   public class ConfigServerApplication {
       public static void main(String[] args) {
           SpringApplication.run(ConfigServerApplication.class, args);
       }
   }
   

5. Now, configure the server in src/main/resources/application.properties. We need to tell it which port to run on and where to find the Git repository.

   # The port for the config server. 8888 is a common convention.
   server.port=8888
   
   # The URI of your Git repository
   spring.cloud.config.server.git.uri=https://github.com/YOUR_USERNAME/spring-cloud-config-repo.git
   

   Replace YOUR_USERNAME with your actual GitHub username.

Test the Config Server

You're ready to test! Run the ConfigServerApplication. Once it starts, open a browser and navigate to:

http://localhost:8888/greeting-service/dev

The server should respond with a JSON object containing the properties from your greeting-service-dev.yml file. This confirms your Config Server is successfully reading from the Git repository.

Example output from the Config Server endpoint, showing properties fetched from the Git repository for the 'greeting-service' application and 'dev' profile.

Step 3: Build a Config Client

Now let's create a microservice that consumes configuration from our new server.

1. Go back to start.spring.io.

2. Set up a new client project:

   • Project: Maven
   • Language: Java
   • Group: com.example
   • Artifact: greeting-service
   • Dependencies: Spring Web, Config Client, Spring Boot Actuator.

3. Generate and open this new project in your IDE.

4. Configure the client to connect to the Config Server. In Spring Boot 2.4 and later, this is done using spring.config.import. Create a file named src/main/resources/application.properties and add:

   # The name of this application. It MUST match the name of the config file in Git (greeting-service.yml).
   spring.application.name=greeting-service
   
   # The active profile. This determines which profile-specific file to load (greeting-service-dev.yml).
   spring.profiles.active=dev
   
   # Tell Spring Boot to import configuration from a Config Server.
   # The 'optional:' prefix prevents the app from failing to start if the config server is down.
   spring.config.import=optional:configserver:http://localhost:8888
   

5. Create a simple REST controller to display the configured greeting.

   import org.springframework.beans.factory.annotation.Value;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   public class GreetingController {
   
       // Inject the property from the centralized configuration
       @Value("${message.greeting}")
       private String greetingMessage;
   
       @GetMapping("/greeting")
       public String getGreeting() {
           return greetingMessage;
       }
   }
   

Test the Config Client

1. Make sure your Config Server is still running.
2. Run the GreetingServiceApplication. Watch the console logs during startup; you should see a line indicating it's fetching configuration from http://localhost:8888.
3. Once started, open a browser and navigate to http://localhost:8080/greeting.

You should see the message: "Hello from the development profile!". Your client application has successfully loaded its configuration from the central Config Server.

Step 4: Dynamic Configuration Refresh

We've centralized our configuration, but we still have one problem: if we update a property in Git, the client application won't see the change until it's restarted. Let's fix this by enabling dynamic refresh.

Here’s how to enable it in your greeting-service client:

1. Expose the Actuator refresh endpoint. We already added the spring-boot-starter-actuator dependency. Now, add the following line to greeting-service's application.properties:

   # Expose the 'refresh' endpoint over HTTP
   management.endpoints.web.exposure.include=refresh
   

2. Enable refresh on the controller. Add the @RefreshScope annotation to your GreetingController. This tells Spring to create a special proxy for this bean that can be re-initialized when a refresh is triggered.

   import org.springframework.beans.factory.annotation.Value;
   import org.springframework.cloud.context.config.annotation.RefreshScope; // Import this
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   @RefreshScope // Add this annotation
   public class GreetingController {
       // ... rest of the class is the same
   }
   

Test the Refresh Mechanism

The following video walks through exactly what we're about to do.

Now, try it yourself:

1. Restart your greeting-service to apply the new annotations and properties.
2. Go to your spring-cloud-config-repo on GitHub and edit the greeting-service-dev.yml file. Change the message to something new:

   message:
     greeting: "Hello, the config has been refreshed!"
   

   Commit the change.
3. Go back to your browser and refresh http://localhost:8080/greeting. The message will not have changed. The client is still using the old value.
4. Now, trigger the refresh. Open a terminal or a tool like Postman and send an empty POST request to the /actuator/refresh endpoint:

   curl -X POST http://localhost:8080/actuator/refresh
   

   You should get a JSON response listing the properties that were changed (e.g., ["message.greeting"]).
5. Finally, refresh http://localhost:8080/greeting in your browser one more time.

Voila! You should now see the new message: "Hello, the config has been refreshed!". You have successfully updated the configuration of a running microservice without restarting it.

Conclusion

Congratulations! You've just implemented a core component of a robust microservices architecture. Centralizing configuration removes a major source of errors and friction, allowing services to be managed more effectively.

Key Takeaways:

• Centralized Configuration is essential for managing properties across multiple microservices.
• Spring Cloud Config uses a Config Server to serve properties from a backend, typically a Git repository.
• Client applications use the spring.config.import property to connect to the Config Server.
• The @RefreshScope annotation, combined with the /actuator/refresh endpoint, enables dynamic updates to configuration without requiring an application restart.

What's Next?

Our services can now be configured from a central location. But how do they find each other in a dynamic cloud environment where IP addresses can change? In the next lesson, you will implement service discovery using a registry like Eureka. This will be the next step in building our interconnected microservices landscape.