Federation Reference

Overview

This guides provides a reference on all the fields that can be set when defining various parameters related to federation.

Please refer to other federation-related guides to learn about the concepts and how to get started.

Configuration Reference

Policies

A policy can apply an upstream set (including the implicitly-defined upstream set named "all") or a single upstream to a set of exchanges and/or queues.

To apply all upstreams:

rabbitmqctl set_policy federate-me '^federated\.' '{"federation-upstream-set":"all"}'

To apply a named set of upstreams:

rabbitmqctl set_parameter federation-upstream-set location-1 '[{"upstream": "up-1"}, {"upstream": "up-2"}]'

rabbitmqctl set_policy federate-me '^federated\.' '{"federation-upstream-set":"location-1"}'

To apply a single upstream:

rabbitmqctl set_policy federate-me '^federated\.' '{"federation-upstream":"up-1"}'

Note that you cannot use the federation-upstream and federation-upstream-set keys together in a policy. For more detail on policies, see the policy documentation.

Upstreams

A federation-upstream parameter specifies how to connect to a remote node or cluster as well as certain properties of a link (connection). Upstreams are defined using the rabbitmqctl set_parameter federation-upstream command which accepts an upstream name and an upstream definition JSON object:

rabbitmqctl set_parameter federation-upstream <i>name</i> '<i>json-object</i>'

The upstream definition object can contain the following keys:

Applicable to Both Federated Exchanges and Queues

Parameter Name	Description
uri	The AMQP URI(s) for the upstream. See the query parameter reference for the underlying client library extensions (including those for TLS) which are available to federation. The value can either be a string, or a list of strings. If more than one string is provided, the federation plugin will randomly pick one URI from the list when attempting to connect. This can be used to connect to an upstream cluster and ensure the link will eventually find another node in the event that one fails. All URIs are assumed to be pointed at nodes in a single cluster. To connect to multiple endpoints in separate clusters simultaneously use multiple upstreams.
prefetch-count	The maximum number of deliveries pending acknowledgement on a link at any given time. Default is 1000. Increasing this value can improve link throughput up to a point but will also result in higher memory usage of the link.
reconnect-delay	The duration (in seconds) to wait before reconnecting to the broker after being disconnected. Default is 1.
ack-mode	Determines how the link should acknowledge messages. If set to on-confirm (the default), messages are acknowledged to the upstream broker after they have been confirmed downstream. This handles network errors and broker failures without losing messages, and is the slowest option. If set to on-publish, messages are acknowledged to the upstream broker after they have been published downstream. This handles network errors without losing messages, but may lose messages in the event of broker failures. If set to no-ack, message acknowledgements are not used. This is the fastest option, but may lose messages in the event of network or broker failures.
trust-user-id	Determines how federation should interact with the validated user-id feature. If set to true, federation will pass through any validated user-id from the upstream, even though it cannot validate it itself. If set to false or not set, it will clear any validated user-id it encounters. You should only set this to true if you trust the upstream server (and by extension, all its upstreams) not to forge user-ids.

Applying to Federated Exchanges Only

The following upstream parameters are only applicable to federated exchanges.

Parameter Name	Description
exchange	The name of the upstream exchange. Default is to use the same name as the federated exchange.
max-hops	The maximum number of federation links that a message published to a federated exchange can traverse before it is discarded. Default is 1. Note that even if max-hops is set to a value greater than 1, messages will never visit the same node twice due to travelling in a loop. However, messages may still be duplicated if it is possible for them to travel from the source to the destination via multiple routes.
queue-type	The queue type of the internal upstream queue used by exchange federation. Defaults to classic (a single replica queue type). Set to quorum to use a replicated queue type. Changing the queue type will delete and recreate the upstream queue by default. This may lead to messages getting lost or not routed anywhere during the re-declaration. To avoid that, set resource-cleanup-mode key to never. This requires manually deleting the old upstream queue so that it can be recreated with the new type. Available since: 3.13.1
resource-cleanup-mode	Whether to delete the internal upstream queue when federation links stop. By default, the internal upstream queue is deleted immediately when a federation link stops. Set to never to keep the upstream queue around and collect messages even when changing federation configuration.
expires	The expiry time (in milliseconds) after which an upstream queue for a federated exchange may be deleted if a connection to the upstream is lost. The default is 'none', meaning no expiration will be applied to the queue. This setting controls how long the upstream queue will last before it is eligible for deletion if the connection is lost. This value controls TTL settings for the upstream queue.
message-ttl	The expiry time for messages in the upstream queue for a federated exchange (see expires), in milliseconds. Default is 'none', meaning messages should never expire. This does not apply to federated queues. This value controls TTL settings for the messages in the upstream queue.

Applicable to Federated Queues Only

Parameter Name	Description
queue	The name of the upstream queue. Default is to use the same name as the federated queue.
consumer-tag	The consumer tag to use when consuming from upstream. Optional.

Upstream Sets

Each upstream-set is a set of upstreams. It can be more convenient to use a set and refer to it in a federation policy definition that repeatedly listing upstreams.

# up-1 and up-2 are previously declared upstreams
rabbitmqctl set_parameter federation-upstream-set location-1 '[{"upstream": "up-1"}, {"upstream": "up-2"}]'

Supported keys of the JSON objects are

Parameter Name	Description
upstream	The name of an upstream. Mandatory.

In addition, any of the properties from an upstream can be overridden in an upstream set.

There is an implicitly-defined upstream set, all, which contains all upstreams created in the target virtual host.

cluster name

The federation plugin uses the cluster name defined within the server to identify itself to other nodes in the federation graph. The default is constructed from the RabbitMQ node name and the fully-qualified domain name of the first node to form the cluster.

This can be changed with the

rabbitmqctl set_cluster_name

command or via the management UI.

It is important to specify this explicitly if your DNS will not give machines distinct names.

Here's an Example:

rabbitmqctl set_cluster_name "east1-production"