Nacos Overview

Nacos, derived from Dynamic Naming and Configuration Service, is a platform designed to streamline service discovery, configuration management, and governance in cloud-native environments. It simplifies building, delivering, and managing microservice architectures by offering capabilities for dynamic registration, configuration, metadata handling, and traffic control. Detailed official documentation is available at https://nacos.io/zh-cn/docs/what-is-nacos.html.

Local Nacos Setup

To run Nacos locally for development, ensure JDK 1.8+ is installed. Obtain the distribution from the GitHub releases page. Extract the archive and navigate to the bin directory. Starting the server depends on the desired mode.

Single-Instance Mode:

• Windows: startup.cmd -m standalone
• Linux: startup.sh -m standalone

For Nacos version 2.2.0+ an additional step is mandatory before starting: edit conf/application.properties and set a value for nacos.core.auth.plugin.nacos.token.secret.key. Refer to the authentication documentation for guidelines on generating a custom key.

To permanently switch to standalone mode, edit the startup script directly by changing the MODE variable to standalone.

After startup, access the console at http://localhost:8848/nacos using the default credentials nacos/nacos. Accounts can be managed under the Permission Control > User List menu.

Creating a Spring Boot Demo

Dependency Configuration

A Spring Boot 2.x project requires specific Nacos dependencies. The following Maven pom.xml configuration uses version 2.2.1.RELEASE, but aligning the Nacos starter versions exactly with the Spring Boot release version is strongly recommended.

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.2.1.RELEASE</version>
    <relativePath/>
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
        <version>2.2.1.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        <version>2.2.1.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-core</artifactId>
    </dependency>
</dependencies>

If the Spring Boot version is 2.4 or later, the following dependency must also be included:

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

Core Application Setup

Create a bootstrap.properties file with fundamental settings and Nacos addresses. This file is loaded before the main application context.

spring.application.name=springboot-nacos
server.port=8299
spring.profiles.active=dev

spring.banner.charset=UTF-8
server.tomcat.uri-encoding=UTF-8
spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true
spring.http.encoding.force=true
spring.messages.encoding=UTF-8

nacos.discovery.autoRegister=true
spring.cloud.nacos.discovery.server-addr=http://127.0.0.1:8848
spring.cloud.nacos.config.server-addr=http://127.0.0.1:8848

Define the main application entry point, annotated with @SpringBootApplication and @EnableDiscoveryClient to activate service registraiton.

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient
public class App {
    private static final Logger logger = LoggerFactory.getLogger(App.class);

    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
        logger.info("Program started successfully!");
    }
}

Exposing Configuration via an Endpoint

To observe live configuration, create a REST controller using @RefreshScope. This annotation enables the bean to be reinitialized without a full restart when Nacos pushes a configuration change.

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

import static org.springframework.web.bind.annotation.RequestMethod.GET;

@RestController
@RequestMapping("config")
@RefreshScope
public class ConfigController {

    @Value("${demo.property:fallback-value}")
    private String dynamicValue;

    @RequestMapping(value = "/getValue", method = GET)
    public String exposeValue() {
        return dynamicValue;
    }
}

Managing Data IDs

Nacos resolves configuration using a Data ID. The default naming convention combines the application name and the file extension. When spring.profiles.active is set, the profile becomes part of the Data ID.

Three resolution patterns exist, ordered by specificity:

1. prefix (e.g., springboot-nacos)
2. prefix.file-extension (e.g., springboot-nacos.properties)
3. prefix-spring.profiles.active.file-extension (e.g., springboot-nacos-dev.properties)

Nacos picks the most specific matching Data ID. A configuration published under any of these valid patterns will be loaded.

Advanced Configuration Management

Namespaces and Groups

For multi-environment or multi-tenant setups, isolate configurations using namespaces. Create a new namespace in the Nacos console under the Namespaces menu. The namespace ID must be unique.

When publishing a configuration, assign it to a specific group, such as dev, test, or prod. In the Spring Boot project, reference the namespace and group in bootstrap.properties:

spring.cloud.nacos.config.namespace=pcm-namespace--id
spring.cloud.nacos.config.group=dev
spring.cloud.nacos.config.fileExtension=properties

Replace pcm-namespace--id with the generated ID from the console.

Leveraging Multiple Configuration Files

Distribute large configuration sets across multiple Data IDs for clarity. Define additional sources using extension-configs in bootstrap.properties. Increment the index ([0], [1], etc.) for each extra file.

spring.cloud.nacos.config.extension-configs[0].data-id=pcm-dev.properties
spring.cloud.nacos.config.extension-configs[0].group=dev

Any property defined in an external Data ID can be injected using @Value. For example, if pcm-dev.properties contains user.age=28, a field can be declared as:

@Value("${user.age:18}")
private String userAge;