Learn NATS - Clustering & Leaf Nodes

#Introduction

Up to episode 13, you've been running a single server. Episode 14 spreads the wings: clustering for high availability and leaf nodes for reaching the edge and multi-region. This is when NATS changes from a system on one machine into distributed infrastructure.

We'll cover cluster mode and Raft consensus for JetStream, gateways between clusters, tolerance to node loss, then leaf nodes for IoT, edge, and multi-region federation scenarios.

#Cluster Mode: Many Servers, One System

#The Cluster Concept

A cluster is a group of interconnected NATS servers that share subject routing. Clients can connect to any server — messages flow automatically toward the right server.

cluster {
  name: "nats-prod"
  listen: "0.0.0.0:6222"
  routes: ["nats-route://nats-a:6222", "nats-route://nats-b:6222"]
}

The cluster block defines the cluster name, the route port 6222 for inter-server communication, and the list of routes. Servers carrying the same route list automatically form a cluster. Port 4222 stays for clients, 6222 for server gossip.

#Running a Three-Node Cluster

Three servers with routes pointing at each other form a cluster:

nats-server -c cluster-a.conf
nats-server -c cluster-b.conf
nats-server -c cluster-c.conf

The nats-server -c cluster-a.conf command and the other two start three nodes. Clients just connect to any one of them — NATS handles cross-node routing transparently.

#Raft Consensus for JetStream

#Keeping Streams Consistent

JetStream in a cluster uses Raft consensus to ensure all stream copies are consistent. When a message is published with replicas 3, the servers form a Raft group that elects a leader for each stream.

nats stream report

nats stream report shows the replication status of every stream. The Replicas column shows active copies, and Cluster shows whether the stream is healthy. Raft consensus ensures only one leader writes, and followers keep up.

#Tolerance to Node Loss

A three-node cluster can lose one node and keep operating; a five-node cluster can lose two. General rule: tolerance = (node count - 1) / 2 for odd counts.

3 node  -> tolerates 1 dead node
5 node  -> tolerates 2 dead nodes
4 node  -> tolerates 1 dead node (more expensive, no benefit)

The 5 node -> tolerates 2 dead nodes scheme explains why odd node counts are more efficient: a fourth node only adds cost without adding tolerance. When a leader dies, Raft automatically elects a new one.

#Gateways Between Clusters

#Connecting Different Clusters

A gateway connects two clusters with different names — usually in different regions or data centers — for exchanging specific subjects.

gateway {
  name: "region-a"
  listen: "0.0.0.0:7222"
  gateways: [
    { name: "region-b", urls: ["nats-gw://gw-b:7222"] }
  ]
}

The gateway block connects the region-a cluster to region-b through port 7222. Unlike clusters that merge routing, a gateway only forwards allowed subjects — great for separating load and keeping isolation between regions.

#When to Use a Gateway

Use gateways when you want to share messages between autonomous clusters, for example important events from one region to another. Use clusters when nodes must share the same streams and state.

#Leaf Nodes: Reaching the Edge

#Connecting Edge Servers to a Hub

A leaf node connects a NATS server (for example on an edge device) to a central server as if they were one system. Local subjects on the edge server can be accessed from the hub, and vice versa.

leafnodes {
  remotes: [
    { url: "nats-leaf://hub.internal:7422" }
  ]
}

The leafnodes block on the edge server connects it to the hub server through port 7422. A leaf node can keep running offline — local messages are processed on its own, and when the connection is restored, messages are exchanged.

#NATS in IoT and Multi-Region Federation

Leaf nodes are a great fit for IoT:

factory gateway (leaf) --> cloud hub (leaf) --> data center
sensor devices (leaf)  --> city server   --> regional center

The sensor devices (leaf) structure shows edge devices reporting data to a local server, which then forwards it to the hub. This pattern yields a resilient multi-region federation architecture: data is still processed close to its source, and synchronization happens without disturbing local latency.

#Conclusion

Episode 14 brought NATS to distributed scale: multi-server clusters with Raft consensus for JetStream, gateways for connecting clusters across regions, node-loss tolerance determined by replica count, and leaf nodes for reaching the edge, IoT, and multi-region federation.

Key takeaways:

• Clusters merge many nodes into one system with shared routing.
• JetStream uses Raft consensus to keep streams consistent.
• A 3-node cluster tolerates one node loss; 5-node tolerates two.
• Gateways connect different clusters for exchanging selected subjects.
• Leaf nodes connect edge servers to a hub as one system.
• Leaf nodes support IoT, edge, and multi-region federation architectures.

In episode 15 next, we'll discuss integration & best practices — NATS as an MQTT broker for IoT devices via the mqtt configuration block, then a summary of subject naming conventions, backpressure, timeouts, and the correct event-driven patterns for microservices. This is the bridge toward advanced optimization.