| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.18"> |
| <link rel="icon" type="image/png" href="images/favicon.png"> |
| <title>Federation</title> |
| <link rel="stylesheet" href="css/asciidoctor.css"> |
| <link rel="stylesheet" href="css/font-awesome.css"> |
| <link rel="stylesheet" href="css/rouge-github.css"> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>Federation</h1> |
| <div id="toc" class="toc2"> |
| <div id="toctitle"><a href="index.html">User Manual for 2.33.0</a></div> |
| <ul class="sectlevel1"> |
| <li><a href="#benefits">1. Benefits</a> |
| <ul class="sectlevel2"> |
| <li><a href="#wan">1.1. WAN</a></li> |
| <li><a href="#loose-coupling-of-brokers">1.2. Loose Coupling of Brokers</a></li> |
| <li><a href="#dynamic-and-selective">1.3. Dynamic and Selective</a></li> |
| </ul> |
| </li> |
| <li><a href="#address-federation">2. Address Federation</a></li> |
| <li><a href="#queue-federation">3. Queue Federation</a></li> |
| <li><a href="#wan-full-mesh">4. WAN Full Mesh</a></li> |
| <li><a href="#configuring-federation">5. Configuring Federation</a> |
| <ul class="sectlevel2"> |
| <li><a href="#large-messages">5.1. Large Messages</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Federation allows transmission of messages between brokers without requiring clustering.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A federated address can replicate messages published from an upstream address to a local address. |
| n.b. |
| This is only supported with multicast addresses.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A federated queue lets a local consumer receive messages from an upstream queue.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A broker can contain federated and local-only components - you don’t need to federate everything if you don’t want to.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="benefits"><a class="anchor" href="#benefits"></a><a class="link" href="#benefits">1. Benefits</a></h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="wan"><a class="anchor" href="#wan"></a><a class="link" href="#wan">1.1. WAN</a></h3> |
| <div class="paragraph"> |
| <p>The source and target servers do not have to be in the same cluster which makes federation suitable for reliably sending messages from one cluster to another, for instance across a WAN, between cloud regions or there internet and where the connection may be unreliable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Federation has built in resilience to failure so if the target server connection is lost, e.g. due to network failure, federation will retry connecting to the target until it comes back online. |
| When it comes back online it will resume operation as normal.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="loose-coupling-of-brokers"><a class="anchor" href="#loose-coupling-of-brokers"></a><a class="link" href="#loose-coupling-of-brokers">1.2. Loose Coupling of Brokers</a></h3> |
| <div class="paragraph"> |
| <p>Federation can transmit messages between brokers (or clusters) in different administrative domains:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>they may have different configuration, users and setup;</p> |
| </li> |
| <li> |
| <p>they may run on different versions of ActiveMQ Artemis</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="dynamic-and-selective"><a class="anchor" href="#dynamic-and-selective"></a><a class="link" href="#dynamic-and-selective">1.3. Dynamic and Selective</a></h3> |
| <div class="paragraph"> |
| <p>Federation is applied by policies, that match address and queue names, and then apply.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This means that federation can dynamically be applied as queues or addresses are added and removed, without needing to hard configure each and every one.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Like wise policies are selective, in that they apply with multiple include and exclude matches.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Mutliple policies can applied directly to multiple upstreams, as well policies can be grouped into policy sets and then applied to upstreams to make managing easier.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="address-federation"><a class="anchor" href="#address-federation"></a><a class="link" href="#address-federation">2. Address Federation</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Address federation is like full multicast over the connected brokers, in that every message sent to address on <code>Broker-A</code> will be delivered to every queue on that broker, but like wise will be delivered to <code>Broker-B</code> and all attached queues there.</p> |
| </div> |
| <div class="paragraph"> |
| <div class="title">Address Federation</div> |
| <p><span class="image"><img src="images/federation-address.png" alt="Address Federation"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>For further details please goto <a href="federation-address.html#address-federation">Address Federation</a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="queue-federation"><a class="anchor" href="#queue-federation"></a><a class="link" href="#queue-federation">3. Queue Federation</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Effectively, all federated queues act as a single logical queue, with multiple receivers on multiple machines. |
| So federated queues can be used for load balancing. |
| Typically if the brokers are in the same AZ you would look to cluster them, the advantage of queue federation is that it does not require clustering so is suitable for over WAN, cross-region, on-off prem.</p> |
| </div> |
| <div class="paragraph"> |
| <div class="title">Queue Federation</div> |
| <p><span class="image"><img src="images/federated-queue-symmetric.png" alt="Queue Federation"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>For further details please goto <a href="federation-queue.html#queue-federation">Queue Federation</a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="wan-full-mesh"><a class="anchor" href="#wan-full-mesh"></a><a class="link" href="#wan-full-mesh">4. WAN Full Mesh</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>With federation it is possible to provide a WAN mesh of brokers, replicating with Address Federation or routing and load balancing with Queue Federation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Linking producers and consumers distant from each other.</p> |
| </div> |
| <div class="paragraph"> |
| <div class="title">Example possible full federation mesh</div> |
| <p><span class="image"><img src="images/federated-world-wide-mesh.png" alt="WAN Full Mesh"></span></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="configuring-federation"><a class="anchor" href="#configuring-federation"></a><a class="link" href="#configuring-federation">5. Configuring Federation</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Federation is configured in <code>broker.xml</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Sample:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><federations></span> |
| <span class="nt"><federation</span> <span class="na">name=</span><span class="s">"eu-north-1-federation"</span><span class="nt">></span> |
| <span class="nt"><upstream</span> <span class="na">name=</span><span class="s">"eu-west-1"</span> <span class="na">user=</span><span class="s">"westuser"</span> <span class="na">password=</span><span class="s">"32a10275cf4ab4e9"</span><span class="nt">></span> |
| <span class="nt"><static-connectors></span> |
| <span class="nt"><connector-ref></span>connector1<span class="nt"></connector-ref></span> |
| <span class="nt"></static-connectors></span> |
| <span class="nt"><policy</span> <span class="na">ref=</span><span class="s">"policySetA"</span><span class="nt">/></span> |
| <span class="nt"></upstream></span> |
| <span class="nt"><upstream</span> <span class="na">name=</span><span class="s">"eu-east-1"</span> <span class="na">user=</span><span class="s">"eastuser"</span> <span class="na">password=</span><span class="s">"32a10275cf4ab4e9"</span><span class="nt">></span> |
| <span class="nt"><discovery-group-ref</span> <span class="na">discovery-group-name=</span><span class="s">"ue-west-dg"</span><span class="nt">/></span> |
| <span class="nt"><policy</span> <span class="na">ref=</span><span class="s">"policySetA"</span><span class="nt">/></span> |
| <span class="nt"></upstream></span> |
| |
| <span class="nt"><policy-set</span> <span class="na">name=</span><span class="s">"policySetA"</span><span class="nt">></span> |
| <span class="nt"><policy</span> <span class="na">ref=</span><span class="s">"address-federation"</span> <span class="nt">/></span> |
| <span class="nt"><policy</span> <span class="na">ref=</span><span class="s">"queue-federation"</span> <span class="nt">/></span> |
| <span class="nt"></policy-set></span> |
| |
| <span class="nt"><queue-policy</span> <span class="na">name=</span><span class="s">"queue-federation"</span> <span class="nt">></span> |
| <span class="nt"><exclude</span> <span class="na">queue-match=</span><span class="s">"federated_queue"</span> <span class="na">address-match=</span><span class="s">"#"</span> <span class="nt">/></span> |
| <span class="nt"></queue-policy></span> |
| |
| <span class="nt"><address-policy</span> <span class="na">name=</span><span class="s">"address-federation"</span> <span class="nt">></span> |
| <span class="nt"><include</span> <span class="na">address-match=</span><span class="s">"federated_address"</span> <span class="nt">/></span> |
| <span class="nt"></address-policy></span> |
| <span class="nt"></federation></span> |
| <span class="nt"></federations></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the above example we have shown the basic key parameters needed to configure federation for a queue and address to multiple upstream.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The example shows a broker <code>eu-north-1</code> connecting to two upstream brokers <code>eu-east-1</code> and <code>eu-west-1</code>, and applying queue federation to queue <code>federated_queue</code> , and also applying address federation to <code>federated_address</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong>It is important that federation name is globally unique.</strong></p> |
| </div> |
| <div class="paragraph"> |
| <p>There are many configuration options that you can apply these are detailed in the individual docs for <a href="federation-address.html#address-federation">Address Federation</a> and <a href="federation-queue.html#queue-federation">Queue Federation</a>.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Extra parameters from the URI of a connector-ref can be used to override or provide additional configuration to the ServiceLocator.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="large-messages"><a class="anchor" href="#large-messages"></a><a class="link" href="#large-messages">5.1. Large Messages</a></h3> |
| <div class="paragraph"> |
| <p>If Federation has to process large messages, the default ackBatchSize and consumerWindowSize for the consumer will need to be changed to limit the number of in-flight messages and to enable large message flow. |
| These options can be supplied as parameters on the referenced connector URI, for example: <code>tcp://<host>:<port>?ackBatchSize=100&consumerWindowSize=-1</code></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
