How Nacos Powers Dynamic Service Discovery: Architecture, Protocols, and Code Walkthrough

01 What is Dynamic Service Discovery?

Service discovery uses a registry to record information of all services in a distributed system so that other services can quickly locate the registered services.

In monolithic applications DNS+Nginx can satisfy service discovery, but in microservice architecture the granularity is finer and services go up and down frequently, requiring a registry that can dynamically sense changes and push updated IP lists to consumers.

02 Nacos Implementation of Dynamic Service Discovery

The core principle of Nacos dynamic service discovery is illustrated in the diagram below.

2.1 Communication Protocol

The registration and discovery process relies on a communication protocol. Nacos 1.x only supports HTTP, while 2.x introduced gRPC, a long‑connection protocol that reduces the overhead of frequent HTTP connections and improves performance by more than nine times.

2.2 Nacos Service Registration

Service registration consists of three steps:

Establish a long‑connection: the Nacos SDK resolves the server domain to an IP list, selects one IP, creates a gRPC connection, and monitors its status, reconnecting to the next IP if the connection drops.

Health‑check request: before registration the SDK sends an empty request; if no response is received the server is considered unhealthy and the SDK retries a configurable number of times.

Initiate registration: the SDK inserts a placeholder record into a local cache, marks it successful after the server acknowledges, and runs a periodic task to retry failed registrations.

When registration fails, Nacos SDK automatically compensates via a scheduled task.

Relevant source code:

@Override
public void registerService(String serviceName, String groupName, Instance instance) throws NacosException {
    NAMING_LOGGER.info("[REGISTER-SERVICE] {} registering service {} with instance {}", namespaceId, serviceName, instance);
    // add redo log
    redoService.cacheInstanceForRedo(serviceName, groupName, instance);
    doRegisterService(serviceName, groupName, instance);
}

public void doRegisterService(String serviceName, String groupName, Instance instance) throws NacosException {
    //向服务端发起注册
    InstanceRequest request = new InstanceRequest(namespaceId, serviceName, groupName,
            NamingRemoteConstants.REGISTER_INSTANCE, instance);
    requestToServer(request, Response.class);
    //标记注册成功
    redoService.instanceRegistered(serviceName, groupName);
}

Compensation task implementation:

@Override
public void run() {
    if (!redoService.isConnected()) {
        LogUtils.NAMING_LOGGER.warn("Grpc Connection is disconnect, skip current redo task");
        return;
    }
    try {
        redoForInstances();
        redoForSubscribes();
    } catch (Exception e) {
        Loggers.NAMING_LOGGER.warn("Redo task run with unexpected exception: ", e);
    }
}

private void redoForInstances() {
    for (InstanceRedoData each : redoService.findInstanceRedoData()) {
        try {
            redoForInstance(each);
        } catch (NacosException e) {
            LogUtils.NAMING_LOGGER.error("Redo instance operation {} for {}@@{} failed. ", each.getRedoType(),
                    each.getGroupName(), each.getServiceName(), e);
        }
    }
}

2.3 Nacos Heartbeat Mechanism

Like other registries (Consul, Eureka, Zookeeper, Gsched), Nacos uses heartbeats to detect service offline events. In 1.x the SDK sends periodic HTTP heartbeats; in 2.x the gRPC channel’s built‑in heartbeat keeps the connection alive, and the server treats missing heartbeats as service offline.

2.4 Nacos Service Subscription

When a service goes up or down, Nacos records the client as a subscriber and pushes the latest instance list via gRPC. Clients can also cancel subscriptions, which removes them from the subscriber list.

Key subscription code:

@Override
public void subscribeService(Service service, Subscriber subscriber, String clientId) {
    Service singleton = ServiceManager.getInstance().getSingletonIfExist(service).orElse(service);
    Client client = clientManager.getClient(clientId);
    //校验长连接是否正常
    if (!clientIsLegal(client, clientId)) {
        return;
    }
    //保存订阅数据
    client.addServiceSubscriber(singleton, subscriber);
    client.setLastUpdatedTime();
    //发送订阅事件
    NotifyCenter.publishEvent(new ClientOperationEvent.ClientSubscribeServiceEvent(singleton, clientId));
}

2.5 Nacos Push Mechanism

Earlier Nacos versions used UDP to push instance changes; later versions switched to gRPC for reliability. The server selects the push method based on the client version.

If a push fails (e.g., client restart or unstable network), Nacos retries by re‑queuing the push task and logging delays exceeding one second.

Push task creation code:

private static class PushDelayTaskProcessor implements NacosTaskProcessor {
    private final PushDelayTaskExecuteEngine executeEngine;
    public PushDelayTaskProcessor(PushDelayTaskExecuteEngine executeEngine) {
        this.executeEngine = executeEngine;
    }
    @Override
    public boolean process(NacosTask task) {
        PushDelayTask pushDelayTask = (PushDelayTask) task;
        Service service = pushDelayTask.getService();
        NamingExecuteTaskDispatcher.getInstance()
                .dispatchAndExecuteTask(service, new PushExecuteTask(service, executeEngine, pushDelayTask));
        return true;
    }
}

2.6 Nacos SDK Query Service Instances

Consumers call the SDK to obtain the latest instance list, which is usually served from the local cache updated by pushes. If the cache misses, the SDK falls back to a subscription request or a direct query to the server. A failover mode can load cached data from disk when the server is unavailable.

3. Conclusion

This article introduced the basic concepts and core capabilities of Nacos service discovery, providing a deeper understanding of its registration, heartbeat, subscription, push, and query mechanisms.