Spring Cloud Config provides centralized configuration management for microservices and solves common pain points such as scattered configuration, inconsistent versions, restart-dependent updates, and plaintext storage of sensitive data. This guide covers Server/Client setup, dynamic refresh, Bus broadcasting, and configuration encryption. Keywords: microservices configuration center, dynamic refresh, sensitive data encryption.
Technical specification snapshot
| Parameter | Description |
|---|---|
| Core technologies | Spring Boot, Spring Cloud Config |
| Configuration protocols | HTTP REST, Git WebHook |
| Message broadcasting | Spring Cloud Bus + RabbitMQ |
| Configuration storage | Git (also supports SVN/local file system) |
| Dynamic refresh endpoints | /actuator/refresh, /actuator/busrefresh |
| Encryption capabilities | Symmetric encryption, RSA asymmetric encryption |
| Article popularity | The original article shows 373 views, 7 likes, and 15 bookmarks |
| Core dependencies | config-server, starter-config, actuator, bus-amqp |
Spring Cloud Config is a standard implementation for a microservices configuration center
As the number of microservices grows, configuration files quickly become scattered across different services and environments. If database endpoints, Redis parameters, message queue credentials, and third-party keys continue to be maintained locally, a single change often means redeploying multiple services.
The value of Spring Cloud Config lies in extracting configuration into an independent capability: centralized hosting, environment isolation, version traceability, and runtime refresh support. For small to mid-sized Spring Cloud ecosystems, it remains a low-cost and stable configuration center solution.
It primarily solves four categories of problems
- Configuration changes depend on restart and redeployment.
- Configuration versions are hard to keep consistent across multiple instances.
- Sensitive information enters repositories in plaintext.
- Switching between dev, test, and prod environments is costly.
Configuration flow:
Git repository -> Config Server -> Config Client -> Business classes read configuration
|
Actuator / BusThis diagram shows the minimum closed loop of a configuration center: storage, distribution, consumption, and refresh.
Spring Cloud Config runs on a three-part model
Config Server is the configuration service provider. In essence, it is a Spring Boot application with configuration center capabilities enabled. It reads configuration from Git or a local directory and exposes it through REST endpoints.
Config Client is integrated into business microservices. It reads remote configuration early in the application startup lifecycle and injects configuration into the Environment or business beans.
The Git backend provides version control, which is one of the most practical parts of Spring Cloud Config. You can audit configuration changes, roll them back, separate environments by branch, and integrate them with CI/CD workflows.
The minimum viable setup for Config Server is straightforward
First, add the server-side dependencies and enable the annotation.
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-config-server</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>These dependencies expose the HTTP configuration endpoints for Config Server.
@EnableConfigServer // Enable configuration center server capabilities
@SpringBootApplication
public class ConfigServerApplication {
public static void main(String[] args) {
SpringApplication.run(ConfigServerApplication.class, args); // Start the server
}
}This bootstrap class upgrades a standard Spring Boot application into a configuration server.
Config Server must bind to a versioned configuration repository
It is best practice to store configuration in a dedicated Git repository and specify the directory through search-paths. This decouples the application code repository from the configuration repository and makes permissions easier to manage independently.
server:
port: 7071
spring:
application:
name: config-server
cloud:
config:
server:
git:
uri: https://gitee.com/xxx/config-repo # Configuration repository URL
default-label: master # Default branch
search-paths: config # Configuration file directoryThis configuration defines the service port, Git repository location, and default branch.
In the repository, use the {application}-{profile}.yml naming convention, such as product-service-dev.yml. This allows clients to pull the correct configuration simply by providing the application name and environment.
The server endpoints follow a fixed naming convention
/{application}/{profile}/{application}-{profile}.yml/{label}/{application}-{profile}.yml
For example, visiting http://localhost:7071/config-server-dev.yml lets you verify whether the server successfully pulled configuration from Git.
Config Client connects to the configuration center during the bootstrap phase
The key client dependency is spring-cloud-starter-config. If the project still uses the bootstrap.yml mechanism, you should also add the bootstrap starter to ensure that remote configuration loads before local business configuration.
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-config</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>These dependencies enable remote configuration retrieval in the business service.
spring:
profiles:
active: dev
application:
name: product-service
cloud:
config:
uri: http://127.0.0.1:7071 # Point to Config ServerThis bootstrap.yml determines which server and environment the client reads configuration from.
Business code reads remote properties the same way it reads local configuration
@RestController
@RequestMapping("/config")
public class ConfigController {
@Value("${data.env}")
private String env; // Inject the environment value from remote configuration
@GetMapping("/getEnv")
public String getEnv() {
return "env: " + env; // Return the configuration center result
}
}This controller verifies whether the client successfully retrieved remote configuration.
Dynamic refresh is the key capability that truly improves delivery efficiency
By default, the client pulls configuration only at startup. After the Git repository changes, the service does not detect updates automatically, so you need to introduce Actuator and use refresh endpoints.
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>This dependency enables management endpoints that support hot configuration refresh.
@RefreshScope // Mark this bean so configuration can be re-injected after refresh
@RestController
@RequestMapping("/config")
public class ConfigController {
// Other code omitted
}This annotation ensures that configuration values in the bean are rebound after refresh.
management:
endpoints:
web:
exposure:
include: refresh,health,infoThis configuration explicitly exposes the refresh endpoint.
After modifying the Git configuration, send a request to POST /actuator/refresh to reload configuration for a single instance. This approach works well in development environments or single-node services.
WebHook can turn manual refresh into automated refresh
When a push event occurs in a GitHub or Gitee repository, a WebHook can directly call the client’s /actuator/refresh endpoint. If the service is deployed on a local development machine, you need a tunneling tool to expose the endpoint to the external platform.
This mechanism reduces manual work, but it is still suitable only for a small number of instances. Each instance must receive an individual refresh request, so the maintenance cost grows as the deployment scales.
Spring Cloud Bus turns cluster-wide configuration refresh into a single broadcast
In multi-instance deployments, Spring Cloud Bus is the recommended approach. It converts a configuration change into a message and broadcasts it to all client instances through RabbitMQ or Kafka, enabling unified refresh.
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-bus-amqp</artifactId>
</dependency>This dependency integrates the RabbitMQ-based message bus.
spring:
rabbitmq:
host: 127.0.0.1
port: 5672
username: guest
password: guestThis configuration lets the Server and Client share the same message bus.
After the setup is complete, you only need to call POST /actuator/busrefresh on any instance. Bus then broadcasts the refresh event across the entire cluster. Compared with calling refresh instance by instance, this is the more practical production solution.
Sensitive configuration must use encryption instead of plaintext storage
Config Server includes built-in /encrypt and /decrypt endpoints, allowing you to encrypt configuration before it enters Git. The client does not need to handle decryption details and only reads the final decrypted value.
Symmetric encryption is suitable for fast enablement
encrypt:
key: bite666 # Symmetric key used by the server for encryption and decryptionThis configuration defines a shared symmetric key and works well for simple scenarios that need a quick setup.
When writing ciphertext into the configuration file, add the {cipher} prefix.
data:
password: '{cipher}encrypted-string' # Use the cipher prefix to mark ciphertextThis configuration indicates that the server should decrypt the value before distributing the configuration.
RSA asymmetric encryption is better for high-security scenarios
First, generate a keystore with the JDK keytool.
keytool -genkeypair -keystore D:/config-server.keystore -alias config-server -keyalg RSA -keypass config -storepass configThis command generates the RSA key pair and keystore file.
encrypt:
key-store:
location: config-server.keystore # Keystore location
alias: config-server # Key alias
password: config # storepass
secret: config # keypassThis configuration allows Config Server to use the private key for decryption and raises the protection level for sensitive configuration.
When implementing Spring Cloud Config, you should prioritize three engineering principles
The configuration repository must remain separate from the business repository
This reduces the risk of accidental commits and makes it easier to apply more granular repository access control.
The refresh path must evolve from single-instance refresh to broadcast refresh
Use /refresh in development environments. For production clusters, adopt Bus + MQ directly to avoid inconsistency caused by instance-by-instance refresh.
Sensitive fields must be encrypted by default
Database passwords, AK/SK credentials, and tokens should never enter the repository in plaintext. At minimum, use symmetric encryption. For stricter security requirements, move to RSA.
FAQ
Q1: Why does the client not pick up changes after I update the Git configuration?
A: By default, the client pulls configuration only at startup. Make sure you have added Actuator, exposed the refresh endpoint, and applied @RefreshScope to the target bean.
Q2: What is the difference between /actuator/refresh and /actuator/busrefresh?
A: refresh only refreshes the current instance. busrefresh broadcasts through the message bus to all instances, which makes it suitable for clustered environments.
Q3: Is Spring Cloud Config still a good choice for modern projects?
A: Yes. If your stack is primarily based on Spring Cloud, your configuration scale is moderate, and you need Git-based versioning with lightweight integration, Config remains a stable choice. If you need a more powerful management console, evaluate Nacos or Apollo.
Core summary
This guide systematically reconstructs the core practices of Spring Cloud Config, covering Config Server and Client setup, Git-backed configuration hosting, Actuator-based manual refresh, WebHook-based automatic refresh, Spring Cloud Bus cluster broadcasting, and both symmetric and RSA asymmetric encryption strategies. It helps microservices teams build a configuration center that is traceable, dynamically updatable, and more secure.