How to Seamlessly Integrate Spring Boot with Nacos for Dynamic Configuration and Service Discovery

In microservice architectures, configuration management and service registration/discovery are essential capabilities. Nacos, an open‑source platform from Alibaba, provides both functions and integrates naturally with the Spring Cloud Alibaba stack, enabling dynamic configuration refresh and service discovery.

1️⃣ Environment Preparation

Use Docker to quickly start a standalone Nacos instance for local testing:

# Pull Nacos image (standalone mode)

docker run -d \
  --name nacos \
  -p 8848:8848 \
  -e MODE=standalone \
  -e SPRING_DATASOURCE_PLATFORM=mysql \
  nacos/nacos-server:2.3.0

Note: In production, deploy Nacos in cluster mode and connect it to an external MySQL database. For servers in China, consider using Alibaba Cloud image acceleration.

2️⃣ Integrate Nacos into a Spring Boot Project

2.1 Add Maven or Gradle Dependencies

Maven:

<dependency>
  <groupId>com.alibaba.cloud</groupId>
  <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<dependency>
  <groupId>com.alibaba.cloud</groupId>
  <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

Gradle:

implementation 'com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-config'
implementation 'com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-discovery'

2.2 Configure bootstrap.yml

Use bootstrap.yml (instead of application.yml) so that Nacos settings are loaded early:

spring:
  application:
    name: demo-service  # service name
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
      config:
        server-addr: localhost:8848
        file-extension: yaml

3️⃣ Create Configuration in Nacos

Open the Nacos console at http://localhost:8848/nacos and add a new configuration:

Data ID: demo-service.yaml Group: DEFAULT_GROUP Content:

server:
  port: 8081
custom:
  message: Hello Nacos

4️⃣ Enable Dynamic Refresh

4.1 Expose Refresh Endpoint

Add the following to application.yml:

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

4.2 Use the Configuration

Inject the custom property and expose it via a REST controller:

@RestController
public class DemoController {

    @Value("${custom.message}")
    private String message;

    @GetMapping("/message")
    public String getMessage() {
        return message;
    }
}

When the value of custom.message is changed in Nacos, trigger a refresh with:

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

After the refresh, calling /message returns the updated content.

5️⃣ Production Best Practices

Configuration Isolation: Use separate Namespaces for dev, test, and prod to avoid configuration pollution.

Access Control: Enable Nacos user authentication and assign minimal permissions per service.

Health Checks: Combine Nacos with Kubernetes/Docker health probes to ensure availability.

Version Control: Export Nacos configurations to Git and manage changes via CI/CD pipelines.

6️⃣ Common Issues and Pitfalls

Startup hangs at Nacos connection: Verify that server-addr is reachable and Nacos is running.

Dynamic refresh not working: Ensure you are using bootstrap.yml, the config starter is included, and the /actuator/refresh endpoint is exposed.

Configuration file format errors: Nacos editor does not strictly validate YAML indentation; validate locally before uploading.

Conclusion

Integrating Nacos with Spring Boot gives microservices the ability to register and discover services, centralize configuration, refresh settings at runtime, and enforce environment isolation and permission management, all of which are essential for reliable, scalable backend systems.