Publisher client
Gateway gw-7 is connected through the load balancer to broker-a.
MQTT Cluster Routing Workbench
MQTT Cluster Routing Workbench
Trace how an MQTT broker cluster routes publications, survives node failure, and preserves client state.
animation
mqtt
protocols
clustering
high-availability
Learner-ready MQTT cluster routing workbench with scenario presets, step/play controls, client failover, route-table and retained-state feedback, implementation-specific accuracy notes, source links, and desktop/mobile visual verification.
MQTT Cluster Routing Workbench
Trace a publication through a multi-broker MQTT deployment. MQTT defines the client-to-server protocol; clustering, route tables, state replication, and failover policy are broker implementation choices.
Current route
sensor/gw-7/status -> broker-c
Cluster health
3 active brokers
Client state
connected
Broker output
1 delivery
TrySelect Node failure, Publish burst 1 message, QoS 1, Replicated session store, and Distributed route table before Step.
ObserveCurrent route moves to a surviving broker with about 14 ms cluster hop; Broker output may duplicate 1 QoS message during reconnect if acknowledgement state is uncertain.
ExplainAt QoS 1, MQTT defines client-broker sessions, not cluster replication; broker-specific route tables and state stores must relocate subscriptions, inflight state, retained data, and ownership.
Technical boundariesThe cluster map omits consensus/quorum, split-brain fencing, persistence latency, ordering across nodes, shared storage failure, load-balancer health checks, network partitions, and vendor protocols.
Colour keymqtt identitycurrent / primaryreference / datasuccesscautionerror / failure
1. Connect
2. Subscribe
3. Publish
4. Match route
5. Forward
6. Deliver
Configure cluster path
1 message
message 1
cluster hop: 14 ms
risk: low
Failover client
No reconnect is needed in the healthy path.
Accepts the PUBLISH packet and performs topic matching.
Maintains cluster membership and routing state.
Owns the subscriber connection for sensor/gw-7/status.
Available for scale-out or replacement capacity.
broker-a knows the matching subscriber is attached to broker-c.
Session state is available, so reconnects can resume subscriptions when the broker supports it.
Subscriber client
Dashboard dash-4 is connected to broker-c and subscribes to sensor/+/status.
Routing trace
Step through connect, subscribe, publish, route match, cluster forwarding, and delivery.
Cluster route succeeds
The ingress broker does not need to copy every publication to every node. It needs enough cluster routing state to deliver this matching message to the broker that owns the subscriber session.
Quick reference
What MQTT defines
- CONNECT, SUBSCRIBE, PUBLISH, acknowledgments, sessions, retained messages, and reason codes.
- A client is connected to a server endpoint over one network connection at a time.
- MQTT 5 can include a Server Reference when the server redirects a client.
What clustering adds
- Membership, health checks, route-table exchange, and session or retained-state placement.
- Client failover through reconnect, DNS, a load balancer, or broker-specific redirection.
- Partition handling and consistency rules chosen by the broker implementation.
Do not assume
- No MQTT standard requires leader election for all clusters.
- No MQTT standard requires every publish payload to be replicated to every broker.
- Ordering and duplicate behavior across reconnect still depend on QoS, session state, and implementation.
Technical accuracy notes
Logical broker view
A production cluster can appear as one logical MQTT service to clients, but the internal design can be masterless, quorum-based, sharded, bridge-like, or vendor-specific.
Failover is a reconnect path
If a connected broker fails, affected clients need a new network connection. Whether subscriptions and queued messages resume depends on persistent session state and cluster storage.
Routing comes before replication
Distributed brokers commonly exchange enough routing information to find matching subscriptions. Retained messages, sessions, and durable queues may use separate storage paths.