Dynamic Config Refresh & Secure Settings in Spring Cloud with Nacos & KMS

Introduction

The article explains how to combine Nacos with a Spring Cloud application to enable dynamic configuration updates at runtime, and how to protect sensitive configuration items using Alibaba KMS without modifying business code.

Steps Overview

Integrate Nacos for dynamic configuration refresh

Integrate KMS for zero‑code encryption of sensitive configurations

Explain the working principle of Spring Cloud + Nacos

Spring Cloud Configuration Basics

In a Spring Cloud application, the @Value annotation can read properties from application.properties, environment variables, or JVM arguments, but changes require a restart. Nacos provides a configuration center that can make these properties refreshable at runtime.

Sample application.properties

app.switch=true</code>
<code>app.threadhold=0.8

Sample Spring Bean

@Component
public class AppConfig{
  @Value("${app.switch:false}")
  boolean switch;

  @Value("${app.threadhold}")
  double threadhold;
}

Without Nacos, changing app.switch or app.threadhold requires editing the file and restarting the application.

Integrating Nacos for Dynamic Refresh

Add the Spring Cloud Alibaba Nacos config dependency:

<dependency>
  <groupId>com.alibaba.cloud</groupId>
  <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
  <version>${spring.cloud.alibaba.version}</version>
</dependency>

Configure the external property source in application.properties:

spring.config.import=nacos:pay-application.properties?group=core&refreshEnabled=true
spring.cloud.nacos.config.server-addr={server_addr}

Remove the local app.switch and app.threadhold definitions and let Nacos provide them.

Add @RefreshScope to the bean so that Spring refreshes the fields when Nacos pushes updates:

@Component
@RefreshScope
public class AppConfig{
  @Value("${app.switch:false}")
  boolean switch;

  @Value("${app.threadhold}")
  double threadhold;
}

After restarting, any change to the configuration in Nacos is automatically reflected in the running application.

Protecting Sensitive Configurations with KMS

Sensitive data such as database credentials or tokens should be encrypted. Store encrypted properties in a separate Nacos dataId (e.g., cipher-kms-aes-256-pay-application.properties) with an encrypted. prefix.

# Encrypted database config
encrypted.spring.datasource.driver-class-name=com.mysql.jdbc.Driver
encrypted.spring.datasource.url=jdbc:mysql://localhost:3306/mydatabase
encrypted.spring.datasource.username=user001
encrypted.spring.datasource.password=pass!@#$%

# Encrypted secret and token
encrypted.app.secret=test_GFYIdryujixxx
encrypted.key.token=test_eedsjpp56hko8h

Update the original pay-application.properties to reference the encrypted values:

spring.datasource.driver-class-name=${encrypted.spring.datasource.driver-class-name}
spring.datasource.url=${encrypted.spring.datasource.url}
spring.datasource.username=${encrypted.spring.datasource.username}
spring.datasource.password=${encrypted.spring.datasource.password}

app.secret=${encrypted.app.secret}
key.token=${encrypted.key.token}

app.switch=false
app.threadhold=0.8

Add the MSE KMS extension dependency:

<dependency>
  <groupId>com.alibaba.nacos</groupId>
  <artifactId>nacos-client-mse-extension</artifactId>
  <version>1.0.4</version>
</dependency>

Configure KMS parameters in application.properties:

spring.config.import[0]=nacos:cipher-kms-aes-256-pay-application.properties?group=secret&refreshEnabled=true
spring.config.import[1]=nacos:pay-application.properties?group=core&refreshEnabled=true
spring.cloud.nacos.config.server-addr={server_addr}

spring.cloud.nacos.config.kms_region_id=cn-hangzhou
spring.cloud.nacos.config.kmsEndpoint=kst-xxx.cryptoservice.kms.aliyuncs.com
spring.cloud.nacos.config.kmsVersion=v3.0
spring.cloud.nacos.config.kmsClientKeyFilePath=clientKey_hangzhou.json
spring.cloud.nacos.config.kmsPasswordKey=10xxxd1d
spring.cloud.nacos.config.kmsCaFilePath=clientKey_hangzhou.json

With this setup, the encrypted configuration is stored, transmitted, and cached as ciphertext; the Nacos client automatically decrypts it via KMS at runtime, while the business code remains unchanged.

Dynamic Refresh Mechanism

When refreshEnabled=true is set, Spring Cloud Alibaba (SCA) registers a listener after the Spring context is initialized. Upon a configuration change in Nacos, the client receives a push, triggers a RefreshEvent, and the ContextRefresher updates the Environment and re‑initializes beans annotated with @RefreshScope or @ConfigurationProperties.

Property Source Priority

Spring resolves property values in the order: JVM arguments > environment variables > Nacos (imported via spring.config.import) > local application.properties. This follows Spring Boot’s official external‑config precedence.

Logging and Troubleshooting

Nacos client logs (e.g., config.log) provide insight into listener registration, server push events, data receipt, and callback results. Key log entries include add‑listener , server‑push , data‑received , notify‑listener , notify‑ok , notify‑error , and notify‑block‑monitor . Reviewing these logs helps verify connection details, configuration changes, and any errors during the refresh process.

Conclusion

The guide shows how to achieve runtime configuration refresh in Spring Cloud using Nacos, and how to protect sensitive configuration items with KMS without code changes. It also outlines the underlying mechanisms, property‑source priority, and log‑based troubleshooting, providing a secure and flexible configuration management solution for backend services.