The high-level goal of the Federation plugin is to transmit messages between brokers without requiring clustering. This is useful for a number of reasons.
The federation plugin can transmit messages between brokers (or clusters) in different administrative domains:
The federation plugin uses AMQP 0-9-1 to communicate between brokers, and is designed to tolerate intermittent connectivity.
A broker can contain federated and local-only components to best fit the desired architecture of the system.
Federation does not require O(n2) connections between N brokers (although this is the easiest way to set things up), which should mean it scales better.
The federation plugin allows you to make exchanges and queues federated. A federated exchange or queue can receive messages from one or more upstreams (remote exchanges and queues on other brokers). A federated exchange can route messages published upstream to a local queue. A federated queue lets a local consumer receive messages from an upstream queue.
Federation links connect to upstreams using RabbitMQ Erlang client. Therefore they can connect to a specific vhost, use TLS, use multiple authentication mechanisms.
For more details, see the documentation on federated exchanges and federated queues.
To use federation, one needs to configure two things
The federation plugin is included in the RabbitMQ distribution. To enable it, use rabbitmq-plugins:
rabbitmq-plugins enable rabbitmq_federation
When using the management plugin, you will also want to enable rabbitmq_federation_management:
rabbitmq-plugins enable rabbitmq_federation_management
When using a federation in a cluster, all the nodes of the cluster should have the federation plugin enabled.
Information about federation upstreams is stored in the RabbitMQ database, along with users, permissions, queues, etc. There are three levels of configuration involved in federation:
In practice, for simple use cases you can almost ignore the existence of upstream sets, since there is an implicitly-defined upstream set called all to which all upstreams are added.
Upstreams and upstream sets are both instances of runtime parameters. Like exchanges and queues, each virtual host has its own distinct set of parameters and policies. For more generic information on parameters and policies, see the guide on parameters and policies. For full details on the parameters used by federation, see the federation reference.
Parameters and policies can be set in three ways - either with an invocation of rabbitmqctl, a call to the management HTTP API, or (usually) through the web UI presented by rabbitmq_federation_management. The HTTP API does not present all possibilities - in particular, it does not support management of upstream sets.
Here we will federate all the built-in exchanges except for the default exchange, with a single upstream. The upstream will be defined to buffer messages when disconnected for up to one hour (3600000ms).
First let's define an upstream:
rabbitmqctl |
rabbitmqctl set_parameter federation-upstream my-upstream \ |
---|---|
rabbitmqctl.bat (Windows) |
rabbitmqctl.bat set_parameter federation-upstream my-upstream ^ |
HTTP API |
PUT /api/parameters/federation-upstream/%2f/my-upstream {"value":{"uri":"amqp://target.hostname","expires":3600000}} |
Web UI | Navigate to Admin > Federation Upstreams > Add a new upstream. Enter "my-upstream" next to Name, "amqp://target.hostname" next to URI, and 36000000 next to Expiry. Click Add upstream. |
Then define a policy that will match built-in exchanges and use this upstream:
rabbitmqctl |
rabbitmqctl set_policy --apply-to exchanges federate-me "^amq\." '{"federation-upstream-set":"all"}' |
---|---|
rabbitmqctl (Windows) |
rabbitmqctl.bat set_policy --apply-to exchanges federate-me "^amq\." ^ |
HTTP API |
PUT /api/policies/%2f/federate-me {"pattern":"^amq\.", "definition":{"federation-upstream-set":"all"}, \ |
Management UI | Navigate to `Admin` > `Policies` > `Add / update a policy`. Enter "federate-me" next to "Name", "^amq\." next to "Pattern", choose "Exchanges" from the "Apply to" drop down list and enter "federation-upstream-set" = "all" in the first line next to "Policy". Click "Add" policy. |
We tell the policy to federate all exchanges whose names begin with "amq." (i.e. all the built in exchanges except for the default exchange) with (implicit) low priority, and to federate them using the implicitly created upstream set "all", which includes our newly-created upstream. Any other matching policy with a priority greater than 0 will take precedence over this policy. Keep in mind that federate-me is just a name we used for this example, you can use any string you want there.
The built in exchanges should now be federated because they are matched by the policy. You can check that the policy has applied to the exchanges by checking the exchanges list in management or with:
rabbitmqctl list_exchanges name policy | grep federate-me
And you can check that federation links for each exchange have come up with Admin > Federation Status > Running Links or with:
# This command will be available only if federation plugin is enabled rabbitmqctl federation_status
In general there will be one federation link for each upstream that is applied to an exchange. So for example with three exchanges and two upstreams for each there will be six links.
For simple use this should be all you need - you will probably want to look at the AMQP URI reference.
The federation reference contains more details on upstream parameters and upstream sets.
Inter-node connections used by Federation are based on AMQP 0-9-1 connections. Federation links can be treated as special kind of clients by operators.
Should a link fail, e.g. due to a network interruption, it will attempt to re-connect. Reconnection period is a configurable value that's defined in upstream definition. See federation reference for more details on setting up upstreams and upstream sets.
Links generally try to recover ad infinitum but there are scenarios when they give up:
By increasing reconnect-delay for upstreams it is possible to tolerate higher link failure rates. This is primarily relevant for RabbitMQ installations where a moderate or large number of active links.
Clusters can be linked together with federation just as single brokers can. To summarise how clustering and federation interact:
Federation connections (links) can be secured with TLS. Because Federation uses a RabbitMQ client under the hood, it is necessary to both configure source broker to listen for TLS connections and Federation/Erlang client to use TLS.
To configure Federation to use TLS, one needs to
Just like with "regular" client connections, server's CA should be trusted on the node where federation link(s) runs, and vice versa.
Each combination of federated exchange or queue and upstream needs a link to run. This is the process that retrieves messages from upstream and republishes them downstream. You can monitor the status of federation links using rabbitmqctl and the management plugin.
Federation link status can be inspected using RabbitMQ CLI tools.
Invoke:
# This command will be available only if federation plugin is enabled rabbitmqctl federation_status
This will output a list of federation links running on the target node (not cluster-wide). It contains the following keys:
Parameter Name | Description |
type | exchange or queue depending on what type of federated resource this link relates to |
name | the name of the federated exchange or queue |
vhost | the virtual host containing the federated exchange or queue |
upstream_name | the name of the upstream this link is connected to |
status |
status of the link:
|
connection | the name of the connection for this link (from config) |
timestamp | time stamp of the last status update |
Here's an example:
# This command will be available only if federation plugin is enabled rabbitmqctl federation_status # => [[{type,<<"exchange">>}, # => {name,<<"my-exchange">>}, # => {vhost,<<"/">>}, # => {connection,<<"upstream-server">>}, # => {upstream_name,<<"my-upstream-x">>}, # => {status,{running,<<"<rabbit@my-server.1.281.0>">>}}, # => {timestamp,{{2020,3,1},{12,3,28}}}]] # => ...done.
Enable the rabbitmq_federation_management plugin that extends management UI with a new page that displays federation links in the cluster. It can be found under Admin > Federation Status, or by using the GET /api/federation-links HTTP API endpoint.
If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.
If you'd like to contribute an improvement to the site, its source is available on GitHub. Simply fork the repository and submit a pull request. Thank you!