RabbitMQ Federation Plugin

The Federation plugin links exchanges or queues across separate RabbitMQ brokers, allowing messages to flow between geographically distributed deployments. Unlike Shovel (which drains messages from a source queue), Federation subscribes to messages on upstream brokers and republishes them locally. The original message stays on the upstream broker and is also available locally — making Federation ideal for distributed publish-subscribe scenarios.

The News Agency Analogy

A global news agency has bureaus in London, New York, and Tokyo. Editors in London publish stories to their local broker. Through Federation, the New York and Tokyo bureaus automatically receive those stories in their own local brokers. Each bureau can also publish local stories that federate to the others. Every bureau has a complete local copy of all news, reducing latency for local readers.

Federation vs Shovel

Federation                          Shovel
-------------------------------------------
Subscribes to upstream             Consumes from source queue
Source messages stay upstream      Source messages are removed
Bi-directional possible            One-directional by default
Designed for distributed pub/sub   Designed for point-to-point transfer
Messages flow on demand            Messages always move in bulk
Better for WAN/multi-datacenter    Better for broker migration/draining

Key Components

Upstream

An upstream is the remote broker (or cluster) that Federation connects to for messages. You define upstreams by URI in RabbitMQ parameters.

Federation Link

A federation link is the active connection between the local broker and an upstream. RabbitMQ creates and maintains these links automatically based on policies.

Federated Exchange

A federated exchange receives messages from an upstream exchange. The local exchange subscribes to the upstream using an internal queue. Messages published to the upstream exchange are forwarded to the local federated exchange.

Federated Queue

A federated queue pulls messages from an upstream queue when local consumers need them. It only fetches messages when local consumers are waiting — it does not continuously drain the upstream.

Enabling Federation

rabbitmq-plugins enable rabbitmq_federation
rabbitmq-plugins enable rabbitmq_federation_management  # adds UI tab

Setting Up Exchange Federation

Step 1: Define an Upstream

rabbitmqctl set_parameter federation-upstream london-broker \
  '{"uri":"amqp://user:pass@london.broker.example.com","expires":3600000}'

Step 2: Create a Policy to Federate Exchanges

rabbitmqctl set_policy federate-news "^news\." \
  '{"federation-upstream-set":"all"}' \
  --apply-to exchanges

This policy federates all exchanges whose names start with news. using all defined upstreams.

How Messages Flow

London Broker:
  Producer publishes to exchange "news.breaking"

New York Broker (federated):
  Exchange "news.breaking" is locally declared + federated
  Federation link pulls messages from London
  Local consumers receive London's messages as if published locally

Setting Up Queue Federation

Step 1: Define upstream (same as above)

Step 2: Create a Policy for Queue Federation

rabbitmqctl set_policy federate-tasks "^federated\." \
  '{"federation-upstream-set":"all"}' \
  --apply-to queues

Any queue whose name starts with federated. becomes federated. When local consumers subscribe but the local queue is empty, Federation pulls messages from the upstream queue.

Multi-Hop Federation

Federation supports message forwarding across multiple hops. A message published in London can federate to New York, which federates to São Paulo. Configure this by setting the max-hops parameter:

rabbitmqctl set_parameter federation-upstream london-broker \
  '{"uri":"amqp://london.example.com","max-hops":2}'

A max-hops of 2 allows messages to travel through two federation links before stopping. This prevents infinite forwarding loops in circular topologies.

Federation Link Status

# Via CLI
rabbitmqctl federation_status

# Via Management UI
Admin → Federation Status

Output shows each link with its state:

Exchange: news.breaking  Upstream: london-broker  Status: running
Queue:    federated.q1   Upstream: london-broker  Status: running

Link states: starting, running, idle, stopped.

Upstream Sets

An upstream set is a named group of upstreams. Instead of specifying each upstream individually in every policy, you group them and reference the set name. The built-in set all automatically includes every defined upstream.

# Create a named upstream set
rabbitmqctl set_parameter federation-upstream-set eu-brokers \
  '[{"upstream":"london-broker"},{"upstream":"frankfurt-broker"}]'

# Use the set in a policy
rabbitmqctl set_policy federate-eu "^eu\." \
  '{"federation-upstream-set":"eu-brokers"}' \
  --apply-to exchanges

Real-World Use Cases

Global pub/sub: Events published in a US data center federate to EU and Asia-Pacific data centers. Local consumers in each region receive messages with minimal latency.
Active-active deployments: Each data center runs its own broker. Federation links them so publishers in any region reach consumers in all regions.
Disaster recovery: A secondary broker in a DR site federates queues from the primary site. If the primary fails, the secondary already has recent messages.

Summary

The Federation plugin connects separate RabbitMQ brokers by subscribing to upstream exchanges or queues. Messages flow from upstream brokers to the local broker on demand. Enable it with rabbitmq-plugins enable rabbitmq_federation. Define upstreams by URI, then apply federation via policies. Use max-hops to control multi-hop forwarding depth. Federation is the best tool for geographically distributed RabbitMQ deployments where each region needs its own local broker with access to messages from other regions.

Previous lesson

Back to course

Next lesson