How Nacos Enables Dynamic Configuration Management: A Step‑by‑Step Guide

Dynamic configuration is one of Nacos’s three core functions, allowing centralized and real‑time management of application settings across environments.

Dynamic Configuration

We explore how Nacos manages dynamic configuration in a simple, elegant, and efficient way.

Environment Preparation

First, obtain a Nacos server either by compiling from source or downloading a release package.

Compile from source

Download the release package

Below is the command used to compile Nacos (assuming Java and Maven are configured): mvn -Prelease -nacos clean install -U After a successful build, the distribution directory contains two zip files identical to the official release packages. Extract them and run startup.sh to launch a standalone Nacos server.

Start Server

Run the following command to start the server: sh startup.sh -m standalone Once started, the console is accessible with the default credentials (username: nacos, password: nacos).

Create Configuration

In the console, create a simple configuration item.

Start Client

After the server and configuration are ready, instantiate a Nacos ConfigService to receive data.

The client prints a message and uses System.in.read() to keep the main thread alive.

Modify Configuration

Update the configuration in the console and click “Publish”. The client receives the latest data automatically.

Applicable Scenarios

Nacos stores configuration centrally; clients retrieve it by dataId and group. When the server’s configuration changes, the client is notified, making it suitable for any scenario that requires externalized configuration, such as database connection strings, rate‑limiting rules, and dynamic traffic routing.

Push or Pull?

The Nacos client does not receive pushes from the server; instead, it maintains a long‑polling task that periodically pulls updates.

Create ConfigService

ConfigService

is created via ConfigFactory, which uses reflection to instantiate NacosConfigService with a Properties argument.

Instantiate ConfigService

The constructor initializes two key objects: HttpAgent and ClientWorker.

HttpAgent

ServerHttpAgent

performs the actual HTTP calls, while MetricsHttpAgent adds monitoring.

ClientWorker

ClientWorker

holds the HttpAgent and creates two thread pools: one single‑thread executor that runs checkConfigInfo() every 10 ms, and a regular pool for long‑polling tasks.

The checkConfigInfo() method dispatches LongPollingRunnable tasks, each identified by a taskId.

LongPollingRunnable

Each runnable performs two steps: local configuration check and server fetch. The local check reads cached files (e.g.,

~/nacos/config/fixed‑{address}:8848/nacos/snapshot/DEFAULT_GROUP/{dataId}

) to provide fault tolerance.

If the server reports changed dataId s, the client fetches the new content, updates the corresponding CacheData, and recalculates its MD5.

Add Listener

Listeners are attached to CacheData via ClientWorker.addTenantListeners. When the MD5 of CacheData differs from the listener’s stored MD5, safeNotifyListener is invoked, delivering the new configuration to the listener’s receiveConfigInfo method.

CacheData

CacheData

holds dataId, group, content, a list of wrapped listeners, and the MD5 of the content. Updating the content also updates the MD5, which triggers listener callbacks on the next check.

Summary

After creating configuration items on the Nacos server, clients can listen for changes. A scheduled task periodically pulls updates; when a change is detected, the client stores the new data in CacheData, updates its MD5, and notifies attached listeners. Snapshots are saved locally to handle server failures.