Microservices

Implementing Centralized Configuration Using Spring Cloud Config

By Utility Zone · 2025-11-04T15:24:30.512163

Spring Cloud Config provides a centralized server-side solution for managing externalized configuration properties across multiple microservices in a distributed environment. Rather than storing configuration values in individual application properties files, you can maintain them in a central repository (typically Git) and serve them to all client applications dynamically.¹²³

Architecture Overview

The Spring Cloud Config architecture consists of three main components:²³¹

Config Server: A Spring Boot application that reads configuration properties from various backends (Git, local filesystem, databases) and exposes them via REST endpoints to client applications.³¹

Config Repository: A version-controlled repository (usually Git) where all configuration files are stored, enabling versioning, auditing, and rollback capabilities.⁴²

Config Clients: Microservices that fetch their configuration from the Config Server at startup and can dynamically refresh configurations at runtime.⁵⁶

Setting Up Spring Cloud Config Server

Step 1: Create the Config Server Project

Start by creating a new Spring Boot project using Spring Initializer with the following configuration:¹

Dependencies:

Spring Cloud Config Server
Spring Boot Actuator (for management endpoints)
Spring Web

Add Maven Dependency (pom.xml):

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-server</artifactId>
</dependency>

Step 2: Enable Config Server

Annotate your main application class with @EnableConfigServer to transform it into a configuration server:³¹

package com.example.configserver;

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

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConfigServerApplication.class, args);
    }
}

Step 3: Configure Configuration Source

There are multiple ways to store configuration files with Spring Cloud Config Server:³

Option A: Using Git Repository

Configure your Config Server to fetch properties from a Git repository (application.yml):

spring:
  application:
    name: config-server
  cloud:
    config:
      server:
        git:
          uri: https://github.com/username/config-repo.git
          # For local Git repository:
          # uri: file:///path/to/local/config-repo
          username: your-username
          password: your-password
          # Or use SSH:
          # uri: git@github.com:username/config-repo.git

server:
  port: 8888

Option B: Using Local File System

For development or testing, store configurations locally:³

spring:
  application:
    name: config-server
  profiles:
    active: native
  cloud:
    config:
      server:
        native:
          search-locations: file:///C:/Documents/config, file:///D:/config-backup

server:
  port: 8888

Option C: Multiple Configuration Sources

Combine Git and local filesystem sources:³

spring:
  application:
    name: config-server
  profiles:
    active: native, git
  cloud:
    config:
      server:
        native:
          search-locations: file:///C:/Documents/config
        git:
          uri: https://github.com/username/config-repo.git
        repos:
          testapp:
            pattern: test-app
            uri: https://github.com/username/test-app-config.git

Step 4: Create Configuration Repository

If using Git, initialize a Git repository and add configuration files named after your microservices:⁴

cd config-repo
git init

Create property files (application.properties, microservice-specific files):

# application.properties (shared by all services)
logging.level.root=INFO
spring.jpa.show-sql=true

# employee-service.properties
server.port=8081
spring.datasource.url=jdbc:mysql://localhost:3306/employee_db
spring.datasource.username=root
spring.datasource.password=root

# employee-service-dev.properties
server.port=8081
spring.datasource.url=jdbc:mysql://localhost:3306/employee_dev
logging.level.root=DEBUG

# department-service.properties
server.port=8082
spring.datasource.url=jdbc:mysql://localhost:3306/department_db

Commit and push to the repository:

git add .
git commit -m "Initial configuration"
git push origin main

Step 5: Test Config Server

Run the Config Server and access the configuration via REST endpoints:¹

http://localhost:8888/employee-service/dev
http://localhost:8888/employee-service/main
http://localhost:8888/application/prod

The response includes all applicable property sources for the requested service and profile.¹

Setting Up Config Clients

Step 1: Create a Microservice Project

Create a new Spring Boot project with these dependencies:⁷⁶

Dependencies:

Spring Cloud Config Client
Spring Web
Spring Boot Actuator

Add Maven Dependency (pom.xml):

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-config</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Step 2: Configure Client Application Properties

In your client application, configure the connection to the Config Server. Create an application.properties file:⁶⁷

spring.application.name=employee-service
spring.config.import=configserver:http://localhost:8888
spring.profiles.active=dev
server.port=8081
management.endpoints.web.exposure.include=health,info,refresh

Key properties explained:

spring.application.name: Identifies which configuration file to fetch from Config Server (must match filename in repository)
spring.config.import: Location of the Config Server
spring.profiles.active: Specifies which profile-specific configuration to load (dev, prod, test, etc.)
management.endpoints.web.exposure.include: Exposes actuator endpoints for dynamic refresh⁶

Step 3: Access Configuration Properties

Inject configuration properties using @Value annotation:⁷⁶

package com.example.employeeservice;

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

@RestController
public class EmployeeController {
    
    @Value("${spring.datasource.url}")
    private String datasourceUrl;
    
    @Value("${logging.level.root:INFO}")
    private String logLevel;
    
    @GetMapping("/config")
    public String getConfig() {
        return "Database URL: " + datasourceUrl + 
               ", Log Level: " + logLevel;
    }
}

Dynamic Configuration Refresh

By default, configuration properties are loaded only once at application startup. To enable dynamic refresh without restarting the application, use one of these approaches:⁸⁹¹⁰

Approach 1: Using Actuator /refresh Endpoint (Manual Refresh)

Annotate your bean with @RefreshScope to mark it as refreshable:¹¹⁹

package com.example.employeeservice;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RefreshScope
public class EmployeeController {
    
    @Value("${spring.datasource.username}")
    private String dbUsername;
    
    @GetMapping("/username")
    public String getUsername() {
        return "Current username: " + dbUsername;
    }
}

When you update the configuration in the Git repository and commit, trigger a refresh by sending a POST request:⁹

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

The @RefreshScope annotation ensures that the @Value properties are re-evaluated after the refresh is triggered.¹¹⁹

Approach 2: Using Spring Cloud Bus (Automatic Refresh)

For multi-instance scenarios where you need to refresh all service instances automatically, use Spring Cloud Bus with a message broker:¹⁰⁹

Add dependencies (pom.xml):

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bus-amqp</artifactId>
</dependency>

Configure RabbitMQ (application.yml):

spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: guest
    password: guest

management:
  endpoints:
    web:
      exposure:
        include: busrefresh,refresh

Trigger refresh across all instances:¹⁰

curl -X POST http://localhost:8081/actuator/bus-refresh

Property Loading Precedence

Understanding the order in which properties are loaded is crucial for effective configuration management:¹²¹³¹⁴

Loading Order (highest to lowest priority):

Profile-specific files (e.g., application-dev.properties) override non-specific files¹³
Application-specific profile files (e.g., employee-service-dev.properties) override shared profile files¹³
Application-specific files (e.g., employee-service.properties) override shared files¹³
Shared profile files (e.g., application-dev.properties) override shared files¹³
Shared files (e.g., application.properties)¹³
Local properties have higher precedence than Config Server properties¹⁴

Properties file format precedence:

.properties files have higher priority than .yaml files¹³

For multiple active profiles (e.g., spring.profiles.active=dev,local), properties are applied using a last-win strategy where the rightmost profile has the highest precedence.¹³

Securing Sensitive Data with Encryption

Spring Cloud Config supports encryption of sensitive properties like database passwords and API keys:¹⁵¹⁶¹⁷

Symmetric Encryption Setup

1. Enable Encryption (application.yml):

encrypt:
  enabled: true
  key: my-secret-encryption-key-12345

2. Encrypt Sensitive Properties

Send a POST request to the Config Server's encrypt endpoint to encrypt values:¹⁵

curl -X POST http://localhost:8888/encrypt -d "password123"

Response: b4fb33fd916f2a3e92c5eaaf92d5dbd0c7a74e1bc20f1234567890abcdef

3. Store Encrypted Value in Configuration

In your Git repository, prefix encrypted values with {cipher}:

# employee-service.properties
spring.datasource.password={cipher}b4fb33fd916f2a3e92c5eaaf92d5dbd0c7a74e1bc20f1234567890abcdef

4. Decryption Happens Automatically

When the client fetches configuration, Spring Cloud Config automatically decrypts values with the {cipher} prefix using the encryption key.¹⁶¹⁵

Asymmetric Encryption (RSA) Setup

For enhanced security using public/private key pairs:¹⁷¹⁵

1. Generate Key Pair:

keytool -genkeypair -alias config-server -keyalg RSA -keystore config-server.jks -storepass password

2. Configure Server (application.yml):

encrypt:
  key-store:
    location: classpath:config-server.jks
    password: password
    alias: config-server
    secret: password

3. Client Configuration (application.properties):

Clients automatically decrypt using the public key information from the server without needing the private key.¹⁷¹⁵

Configuration File Organization Best Practices

For optimal configuration management across microservices:³

Directory Structure:

config-repo/
├── application.properties          (shared across all services)
├── application-dev.properties      (shared, development profile)
├── application-prod.properties     (shared, production profile)
├── employee-service.properties
├── employee-service-dev.properties
├── employee-service-prod.properties
├── department-service.properties
├── department-service-dev.properties
└── department-service-prod.properties

Naming Convention:

Use {application-name}-{profile}.properties format where:

{application-name} matches spring.application.name in your microservice
{profile} corresponds to spring.profiles.active¹⁸⁶

Complete Example Workflow

1. Update Configuration in Git:

Edit employee-service-dev.properties and change:

logging.level.root=DEBUG

Commit and push:

git add employee-service-dev.properties
git commit -m "Update logging level to DEBUG"
git push origin main

2. Trigger Refresh in Running Service:

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

3. Verify Changes:

curl http://localhost:8081/config

The response now shows the updated configuration values without restarting the application.⁸⁹

Key Advantages of Spring Cloud Config

Centralized Management: All configurations stored in one location, reducing duplication and inconsistency.²³

Version Control: Git-based storage enables tracking changes, auditing, and rolling back to previous configurations.²³

Environment-Specific Configurations: Easily manage different settings for development, testing, and production environments without code changes.⁸³

Dynamic Updates: Configurations refresh without restarting applications, minimizing downtime.⁹⁸

Security: Built-in encryption support protects sensitive data like credentials and API keys.¹⁶¹⁵¹⁷

Scalability: Designed for distributed systems with support for multiple microservices across many environments.⁸³

Spring Cloud Config, combined with Spring Boot and proper configuration practices, provides a robust foundation for managing complex microservices configurations across entire organizations. <span style="display:none">¹⁹²⁰</span>