Scaling Stateless Workers with NATS Queue Groups: A Practical Guide

The Problem: Scaling Workers Without Losing Routing Control

When you have multiple stateless workers processing messages, you need a way to distribute load evenly while keeping the routing logic simple. NATS queue groups solve this by letting multiple subscribers share message delivery on the same subject—each message goes to exactly one worker, and publishers don't need to know about the workers at all.

How Queue Groups Work

A queue group is defined by giving multiple subscribers the same queue name when they subscribe to a subject. NATS then acts as a load balancer, sending each published message to only one member of the group. This is different from regular subjects, where every subscriber gets every message.

The key insight is that publishers just publish to a subject like orders.new. They don't need to know how many workers are listening or what queue group they belong to. NATS handles the routing internally.

Setting Up a Queue Group

Here's how to create a simple queue group using the NATS CLI:

# Terminal 1 - Worker A
nats sub -q workers -s orders.new

# Terminal 2 - Worker B
nats sub -q workers -s orders.new

# Terminal 3 - Publisher
nats pub orders.new "Processing order 123"

In this example, both workers use the same queue name workers. When the publisher sends a message to orders.new, NATS delivers it to either Worker A or Worker B, but never both.

Verifying the Setup

To confirm queue groups are working correctly:

1. Start two subscribers with the same queue name on one subject
2. Publish several messages
3. Verify each message is received by exactly one subscriber

You can also check server monitoring output to see queue group membership:

curl http://localhost:8222/connz | grep -A5 queue

Trade-offs and Limitations

Queue groups don't preserve message order across different group members. If order matters, you'd need to use a single subscriber or JetStream with ordered delivery. Also, if all queue group members disconnect, messages published to the subject are not retained unless you enable JetStream.

Rebalancing happens when members join or leave, which can cause temporary uneven delivery. For example, if Worker A is processing messages and Worker B connects, the first few messages might still go to Worker A before NATS redistributes the load.

Actionable Steps

To get started with queue groups:

• Identify a subject with multiple consumers
• Group those consumers under a single queue name
• Test with a few messages to verify load balancing
• Monitor connection stats to ensure all workers are active

If you need message persistence or ordering guarantees, consider JetStream as an enhancement to basic queue groups.