AMQP Federation Configuration Glossary

Federation configuration occurs in a broker connection element where a set of policies defines the desired address or queue federation and the locality of that federation (local or remote). A single federation instance is supported per broker connection element however each federation instance can contain multiple address and queue policy elements. Address and queue policy configuration exist for both the local and the remote side of the federation over the broker connection. An example of such a federation configuration element follows which contains both local and remote policy elements.

<broker-connections>
  <amqp-connection uri="tcp://HOST:PORT" name="federation-example">
    <federation>
       <local-address-policy name="example-local-address-policy">
         <include address-match="local-address.#" />
         <exclude address-match="local-address.excluded" />
       </local-address-policy>
       <local-queue-policy name="example-local-queue-policy">
         <include address-match="address" queue-match="local-queue" />
       </local-queue-policy>
       <remote-address-policy name="example-remote-address-policy">
         <include address-match="remote-address" />
       </remote-address-policy>
       <remote-queue-policy name="example-remote-queue-policy">
         <include address-match="#" queue-match="remote-queue" />
         <exclude address-match="excluded.#" queue-match="remote-queue-excluded" />
       </remote-queue-policy>
    </federation>
  </amqp-connection>
</broker-connections>

Local or Remote federation policies configure the local or remote broker to perform the federation operation over the defined connection but otherwise use the same configuration attributes and properties. The only difference is whether the federation occurs locally meaning local demand triggers consumers to be created towards the remote broker, or if remote demand triggers consumers to be created towards the local broker (local meaning the one that carries the configuration). For this reason the remainder of this documentation will use local federation policies when showing configuration examples for simplicity.

Federation configuration can contain multiple policies of the same type (address or queue) along with a mix of types as seen in the configuration example above. This allows for policies with differing configurations for federating different addresses and queues within the same broker connection. It is important to note that the policy names must be unique within the federation configuration. The following configuration example demonstrates the mix of policy configurations within a single federation configuration.

<broker-connections>
  <amqp-connection uri="tcp://HOST:PORT" name="federation-example">
    <federation>
       <local-address-policy name="example-local-address-policy-1"
                             auto-delete="true"
                             auto-delete-delay="30000"
                             auto-delete-message-count="0">
         <include address-match="a.local-address.#" />
         <exclude address-match="a.local-address.excluded" />
       </local-address-policy>
       <local-address-policy name="example-local-address-policy-2"
                             auto-delete="false">
         <include address-match="b.local-address.#" />
         <exclude address-match="b.local-address.excluded" />
       </local-address-policy>
    </federation>
  </amqp-connection>
</broker-connections>

It is also supported to have only remote federation policies within a broker connection federation element. In this case the policy is sent across the connection to the remote broker and federation occurs on the remote for the life of that broker connection.

<broker-connections>
  <amqp-connection uri="tcp://HOST:PORT" name="federation-example">
    <federation>
       <remote-queue-policy name="example-remote-queue-policy">
         <include address-match="#" queue-match="remote-queue" />
         <exclude address-match="excluded.#" queue-match="remote-queue-excluded" />
       </remote-queue-policy>
    </federation>
  </amqp-connection>
</broker-connections>

1. Address federation configuration elements

<broker-connections>
  <amqp-connection uri="tcp://HOST:PORT" name="federation-example">
    <federation>
       <local-address-policy name="example-local-address-policy"
                             auto-delete="true"
                             auto-delete-delay="30000"
                             auto-delete-message-count="0"
                             max-hops="1"
                             enable-divert-bindings="true">
         <include address-match="local-address.#" />
         <exclude address-match="local-address.excluded" />
         <property key="amqpCredits" value="100" />
         <property key="amqpLowCredits" value="30" />
         <property key="addressReceiverIdleTimeout" value="0" />
       </local-address-policy>
    </federation>
  </amqp-connection>
</broker-connections>

The address policy element can be configured with the following set of attributes, or if the value is omitted the stated default value will be applied to the deployed policy.

name: The name of the policy, these names should be unique within a broker connection’s federation policy elements.
max-hops: The maximum number of hops that a message can perform to be federated. Default value is 0 and will work for most federation deployments. However, in certain topologies where a loop is configured a higher value may be required to prevent infinite looping of messages.
auto-delete: For address federation, a durable queue is created on the broker from which messages are being federated. Set this property to true to mark the queue for automatic deletion once the initiating broker disconnects and the delay and message count parameters are met. This is a useful option if you want to automate the cleanup of dynamically-created queues. The default value is false, which means that the queue is not automatically deleted.
auto-delete-delay: The amount of time in milliseconds after the initiating broker has disconnected before the created queue can be eligible for auto-delete. The default value is 0 when option is omitted.
auto-delete-message-count: After the initiating broker has disconnected, the maximum number of messages allowed in the remote queue for the queue to be eligible for automatic deletion. The default value is 0.
enable-divert-bindings: Setting to true enables divert bindings to be listened-to for demand. If a divert binding with an address matches the included addresses for the address policy, any queue bindings that match the forwarding address of the divert creates demand. The default value is false.

The following set of elements can be configured within the address policy to control the behavior of the deployed policy. For the policy to actually match any addresses on the target broker an include must be provided at a minimum.

include: The address-match pattern to use to match included addresses, multiple of these can be set per policy.
exclude: The address-match pattern to use to match excluded addresses, multiple of these can be set, or it can be omitted if no excludes are needed.
property: A key / value property setting that allows for configuration options to be set either at the root federation level or within each federation policy that affects some defined behavior of the policy implementation.

2. Queue federation configuration elements

<broker-connections>
  <amqp-connection uri="tcp://HOST:PORT" name="federation-example">
    <federation>
       <local-queue-policy name="example-local-queue-policy" priority-adjustment="-1">
         <include address-match="#" queue-match="remote-queue" />
         <exclude address-match="excluded.#" queue-match="remote-queue-excluded" />
         <property key="amqpCredits" value="0" />
         <property key="amqpPullConsumerCredits" value="1" />
       </local-queue-policy>
    </federation>
  </amqp-connection>
</broker-connections>

The queue policy element can be configured with the following set of attributes, or if the value is omitted the stated default value will be applied to the deployed policy.

name: The name of the policy. These names should be unique within a broker connection’s federation policy elements.
priority-adjustment: When federation consumers are created this value can be used to ensure that those federation consumers have a lower priority value than other local consumers on the same queue. The default is -1.
include-federated: Controls if consumers on a queue which come from federation instances should be counted when observing a queue for demand, by default this value is false and federation consumers are not counted as local demand.

The following set of elements can be configured within the queue policy to control the behavior of the deployed policy.

include: The queue-match pattern to use to match included queues and enforce that a matched queue is also bound to a specific address. Multiple of the include elements can be set per policy, but if none are set all queues would be matched unless there is an exclude configured.
exclude: The queue-match pattern to use to match excluded queues that the policy should ignore. Multiple of these can be set, or it can be omitted if no excludes are needed.
property: A key / value property setting that allows for configuration options to be set either at the root federation level or within each federation policy that affects some defined behavior of the policy implementation.

3. Federation policy property configuration index

The following properties can be set either at the federation element level or set per-policy in order to apply different behaviors to different policies within the same federation configuration. When remote address or queue policies are configured the value of these properties are sent to the remote along with the policies to ensure both sides are operating with the same configurations. Certain value can also be set in the broker connection URI when noted if not set in any of the available locations the configuration default value is used.

Name Type Description Default

Name	Type	Description	Default
attach-timeout	Integer	Controls the timeout value for a federation receiver link attach to complete before the attach attempt is considered to have failed. The value is configured in seconds.	30 (Seconds)
amqpCredits	Integer	Defines the amount of credits to batch to an AMQP receiver link and the top up limit when sending more credit once the credits are determined to be running low. This value will be read from the broker connection URI if one was specified there and not set in the federation policy..	1000 (broker default)
amqpLowCredits	Integer	A low water mark for receiver credits that indicates more should be sent to top it up to the original credit batch size. This value will be read from the broker connection URI if one was specified there and not overridden in the federation policy.	300 (broker default)
amqpPullConsumerCredits	Integer	Defines the amount of credits to batch to an AMQP receiver link and the top up value when sending more credit once the broker has capacity available for them. In order for this value to take affect the `amqpCredits` value must be set to zero. If `amqpCredits` ist set to zero and this option is not configured the default value is used.	100
minLargeMessageSize	Integer	Used to configure the value to use when considering if a message is a large message for federation consumers. This value will be read from the broker connection URI if one was specified there and not overridden in the federation policy.	Broker default
ignoreAddressBindingFilters	Boolean	Used to configure if federation address consumers should filter messages using the filters defined on individual matching address bindings. This value can be used to reduce the amount of messages that are federated for an address if the local consumers use filters but must be enabled with care as it can easily lead to duplicate messages being dispatched from the remote as each unique address binding filter creates a remote consumer with that matching filter. If any filters overlap in the messages they allow to pass or there are bindings without a filter then the remote will be sending the same message to multiple federation consumers in order to provide each group of bindings with their matching messages.	true
ignoreQueueConsumerFilters	Boolean	Used to configure if federation queue consumers should filter messages using the filters defined on individual queue subscriptions. This can be used to prevent multiple subscriptions on the same queue based on local demand with differing subscription filters but does imply that message that don’t match those filters would be federated to the local broker.	false
ignoreQueueConsumerPriorities	Boolean	Used to control if federation queue consumers should apply a consumer priority offset based on the subscription priority or should use a singular priority offset based on policy configuration. This can be used to prevent multiple subscriptions on the same queue based on local demand with differing consumer priorities but does imply that care needs to be taken to ensure remote consumers would still normally have a higher priority value than the configured default priority offset. This value is off by default as that is the safest and simplest to manage as a single offset value is set and all federation consumer will be know to be using that value.	true
amqpUseModifiedForTransientDeliveryErrors	Boolean	Used to configure how a federation receiver should respond to delivery errors indicating that an address is full and cannot accept messages at this time. By default we will send Modified outcomes with the delivery failed value set to true such that the remote will deliver the message again after incrementing the delivery count of the message. Disabling this causes the Rejected outcome to be sent instead which is a terminal outcome which results in message being dropped and possibly sent to a DLA on is configured.	true
amqpLinkQuiesceTimeout	Integer	Defines the time in milliseconds that a receiver will wait before considering a pending quiesce timeout to have failed and should close the link. This option can be used to override the value specified on the connector URI to allow federation to operate with a different default. This timeout applies to AMQP links that are being drained due to a transient delivery error such as the address being full and the address policy is set to send a failed response to the remote sender. If the drain on transient delivery errors option is set to false then this option is ignored.	Broker default (10 minutes)
amqpDrainOnTransientDeliveryErrors	Boolean	Used to control if a federation receiver should drain the link credit when a transient delivery error such as the address being full occurs. This option can be used to override the value specified on the connector URI to allow federation to operate with a different default.	Broker default (true).
receiverQuiesceTimeout	Integer	When a federation receiver link is being drained due to removal of local demand this timeout value enforces a maximum wait for drain and processing of in-flight messages before the link is forcibly terminated with the assumption that the remote is no longer responding.	60s
addressReceiverIdleTimeout	Integer	When a federation address receiver link has been successfully drained after demand was removed from the federated resource, this value controls how long the link can remain in an attached but idle state before it is closed. This can allow for quicker restoration of federated messages if the demand on a queue is removed and re-added quickly as the link is drained of credit but not immediately closed. For address receivers the default is kept short to prevent holding broadcast messages on the remote for a receiver which might not return in a timely manner.	5s
queueReceiverIdleTimeout	Integer	When a federation queue receiver link has been successfully drained after demand was removed from the federated resource, this value controls how long the link can remain in an attached but idle state before it is closed. This can allow for quicker restoration of federated messages if the demand on a queue is removed and re-added quickly as the link is drained of credit but not immediately closed.	60s

attach-timeout

Integer

Controls the timeout value for a federation receiver link attach to complete before the attach attempt is considered to have failed. The value is configured in seconds.

30 (Seconds)

amqpCredits

Integer

Defines the amount of credits to batch to an AMQP receiver link and the top up limit when sending more credit once the credits are determined to be running low. This value will be read from the broker connection URI if one was specified there and not set in the federation policy..

1000 (broker default)

amqpLowCredits

Integer

A low water mark for receiver credits that indicates more should be sent to top it up to the original credit batch size. This value will be read from the broker connection URI if one was specified there and not overridden in the federation policy.

300 (broker default)

amqpPullConsumerCredits

Integer

Defines the amount of credits to batch to an AMQP receiver link and the top up value when sending more credit once the broker has capacity available for them. In order for this value to take affect the amqpCredits value must be set to zero. If amqpCredits ist set to zero and this option is not configured the default value is used.

100

minLargeMessageSize

Integer

Used to configure the value to use when considering if a message is a large message for federation consumers. This value will be read from the broker connection URI if one was specified there and not overridden in the federation policy.

Broker default

ignoreAddressBindingFilters

Boolean

Used to configure if federation address consumers should filter messages using the filters defined on individual matching address bindings. This value can be used to reduce the amount of messages that are federated for an address if the local consumers use filters but must be enabled with care as it can easily lead to duplicate messages being dispatched from the remote as each unique address binding filter creates a remote consumer with that matching filter. If any filters overlap in the messages they allow to pass or there are bindings without a filter then the remote will be sending the same message to multiple federation consumers in order to provide each group of bindings with their matching messages.

true

ignoreQueueConsumerFilters

Boolean

Used to configure if federation queue consumers should filter messages using the filters defined on individual queue subscriptions. This can be used to prevent multiple subscriptions on the same queue based on local demand with differing subscription filters but does imply that message that don’t match those filters would be federated to the local broker.

false

ignoreQueueConsumerPriorities

Boolean

Used to control if federation queue consumers should apply a consumer priority offset based on the subscription priority or should use a singular priority offset based on policy configuration. This can be used to prevent multiple subscriptions on the same queue based on local demand with differing consumer priorities but does imply that care needs to be taken to ensure remote consumers would still normally have a higher priority value than the configured default priority offset. This value is off by default as that is the safest and simplest to manage as a single offset value is set and all federation consumer will be know to be using that value.

true

amqpUseModifiedForTransientDeliveryErrors

Boolean

Used to configure how a federation receiver should respond to delivery errors indicating that an address is full and cannot accept messages at this time. By default we will send Modified outcomes with the delivery failed value set to true such that the remote will deliver the message again after incrementing the delivery count of the message. Disabling this causes the Rejected outcome to be sent instead which is a terminal outcome which results in message being dropped and possibly sent to a DLA on is configured.

true

amqpLinkQuiesceTimeout

Integer

Defines the time in milliseconds that a receiver will wait before considering a pending quiesce timeout to have failed and should close the link. This option can be used to override the value specified on the connector URI to allow federation to operate with a different default. This timeout applies to AMQP links that are being drained due to a transient delivery error such as the address being full and the address policy is set to send a failed response to the remote sender. If the drain on transient delivery errors option is set to false then this option is ignored.

Broker default (10 minutes)

amqpDrainOnTransientDeliveryErrors

Boolean

Used to control if a federation receiver should drain the link credit when a transient delivery error such as the address being full occurs. This option can be used to override the value specified on the connector URI to allow federation to operate with a different default.

Broker default (true).

receiverQuiesceTimeout

Integer

When a federation receiver link is being drained due to removal of local demand this timeout value enforces a maximum wait for drain and processing of in-flight messages before the link is forcibly terminated with the assumption that the remote is no longer responding.

60s

addressReceiverIdleTimeout

Integer

When a federation address receiver link has been successfully drained after demand was removed from the federated resource, this value controls how long the link can remain in an attached but idle state before it is closed. This can allow for quicker restoration of federated messages if the demand on a queue is removed and re-added quickly as the link is drained of credit but not immediately closed. For address receivers the default is kept short to prevent holding broadcast messages on the remote for a receiver which might not return in a timely manner.

queueReceiverIdleTimeout

Integer

When a federation queue receiver link has been successfully drained after demand was removed from the federated resource, this value controls how long the link can remain in an attached but idle state before it is closed. This can allow for quicker restoration of federated messages if the demand on a queue is removed and re-added quickly as the link is drained of credit but not immediately closed.

60s