Understanding Nacos Temporary vs Persistent Instances: When to Use Each

Nacos Temporary vs Persistent Instances

When a Nacos client registers a service, it uses the Instance object. The ephemeral boolean field, introduced in version 1.0.0, indicates whether the instance is temporary (ephemeral) or persistent.

public class Instance implements Serializable {
    /**
     * If instance is ephemeral.
     * @since 1.0.0
     */
    private boolean ephemeral = true;
    // ... other fields omitted
}

Across both Nacos 1.x (HTTP) and 2.x (gRPC) versions, the default value of ephemeral remains true, meaning instances are registered as temporary by default. This default can be overridden through application configuration.

# false for permanent instance, true for temporary instance
spring.cloud.nacos.discovery.ephemeral=false

Differences Between Temporary and Persistent Instances

Temporary (ephemeral) instances are not persisted on the server. They stay alive only while the client sends heartbeat messages (default interval 5 seconds). If Nacos does not receive a heartbeat for 15 seconds, the instance is marked unhealthy; after 30 seconds of no heartbeat it is removed.

Persistent instances are stored on the server. When they disappear, Nacos marks them unhealthy but does not delete them, allowing operators to see their status.

The ephemeral flag also determines the health‑check mode: true corresponds to client‑side heartbeat (client mode), while false switches to server‑side health checks (server mode).

Why Two Modes Exist?

Temporary instances are ideal for scenarios with sudden traffic spikes. When health checks fail, the instance is removed automatically, enabling rapid scaling down after the burst.

Persistent instances provide operational visibility. Even if health checks fail, the instance remains in the registry, allowing operators to monitor, alert, and take corrective actions such as manual scaling.

Beyond these use cases, persistent instances play a crucial role in Nacos’s protection‑threshold mechanism.

Protection Threshold in Nacos

Nacos allows setting a protection threshold (a float between 0 and 1) that represents the ratio of healthy instances to total instances for a service.

When the healthy‑instance ratio falls below the threshold, Nacos treats the situation as a potential avalanche risk. Instead of returning only healthy instances, it returns **all** instances (healthy and unhealthy). This ensures that downstream services still receive some instance information, reducing the chance of a complete traffic collapse.

Persistent instances are especially valuable here: even if they are unhealthy, they are still returned during protection‑threshold activation, providing fallback capacity that temporary instances alone could not supply.

Conclusion

The article covered how Nacos distinguishes temporary and persistent instances, how to configure the ephemeral flag, the operational implications of each mode, and the role of the protection threshold in preventing cascade failures. For deeper insight, readers are encouraged to examine the source code, preferably the HTTP‑based implementation for better readability.