4.22. アドレスおよびキューのフェデレーション

手順

1. <broker_instance_dir>/etc/broker.xml 設定ファイルを開きます。

2. <amqp-connection> 要素を含む <broker connections> 要素を追加します。<amqp-connection> 要素で、リモートブローカーの接続詳細を指定し、フェデレーション設定に名前を割り当てます。以下に例を示します。

   <broker-connections>
     <amqp-connection uri="tcp://<__HOST__>:<__PORT__>" user="federation_user" password="federation_pwd" name="queue-federation-example">
     </amqp-connection>
   </broker-connections>

3. <federation> 要素を追加し、次のいずれかまたは両方を含めます。

   • リモートブローカーからローカルブローカーにメッセージをフェデレーションするための <local-address-policy> 要素。
   • ローカルブローカーからリモートブローカーにメッセージをフェデレーションするための <remote-address-policy> 要素。

   次の例は、ローカルアドレスポリシーとリモートアドレスポリシーの両方を含む federation 要素を示しています。

   <broker-connections>
     <amqp-connection uri="tcp://<__HOST__>:<__PORT__>" user="federation_user" password="federation_pwd" name="queue-federation-example">
       <federation>
         <local-address-policy name="example-local-address-policy" auto-delete="true" auto-delete-delay="1" auto-delete-message-count="2" max-hops="1" enable-divert-bindings="true">
           <include address-match="queue.news.#" />
   	    <include address-match="queue.bbc.news" />
           <exclude address-match="queue.news.sport.#" />
          </local-address-policy>
          <remote-address-policy name="example-remote-address-policy">
            <include address-match="queue.usatoday" />
          </remote-address-policy>
       </federation>
     </amqp-connection>
   </broker-connections>

   ローカルアドレスポリシーとリモートアドレスポリシーの両方で同じパラメーターを設定できます。有効なパラメーターは次のとおりです。

   name

   アドレスポリシーの名前。すべてのアドレスポリシー名が、<broker-connections> 要素内の <federation> 要素内で一意である必要があります。

   max-hops

   フェデレーション中にメッセージが実行できるホップの最大数。デフォルト値の 0 は、ほとんどの単純なフェデレーションデプロイメントに適しています。ただし、トポロジーによっては、メッセージのループを防ぐために、より大きな値が必要になる場合があります。

   auto-delete

   アドレスフェデレーションでは、メッセージがフェデレーション統合されるブローカー上に永続キューが作成されます。このパラメーターを true に設定すると、開始ブローカーが切断され、遅延およびメッセージ数のパラメーターが満たされたときにキューが自動的に削除されるようにマークされます。動的に作成されたキューのクリーンアップを自動化する場合に便利なオプションです。デフォルト値は false です。これは、キューが自動的に削除されないことを意味します。

   auto-delete-delay

   開始ブローカーが切断された後、作成されたキューが自動的に削除されるまでの時間 (ミリ秒単位)。デフォルト値は 0 です。

   auto-delete-message-count

   キューを自動的に削除する前に、キューのメッセージ数がこの値以下である必要があります。デフォルト値は 0 です。

   enable-divert-bindings

   true に設定すると、要求に応じて迂回バインディングをリッスンできるようになります。アドレスを持つ迂回バインディングがアドレスポリシーに含まれるアドレスと一致する場合、迂回の転送アドレスと一致するキューバインディングによって要求が作成されます。デフォルト値は false です。

   include

   ポリシーに含めるアドレスに一致するアドレス一致パターン。複数のパターンを指定できます。パターンを指定しなかった場合、すべてのアドレスがポリシーに含まれます。

   正確なアドレス (例: queue.bbc.news) を指定できます。または、ワイルドカード文字である番号記号 (#) を使用して、一致するアドレスのセットを指定することもできます。上記の例では、ローカルアドレスポリシーに、queue.news 文字列で始まるすべてのアドレスも含まれます。

   exclude

   ポリシーから除外するアドレスに一致するアドレス一致パターン。複数のパターンを指定できます。パターンを指定しなかった場合、ポリシーからアドレスは除外されません。

   正確なアドレス (例: queue.bbc.news) を指定できます。または、ワイルドカード文字である番号記号 (#) を使用して、一致するアドレスのセットを指定することもできます。上記の例では、ローカルアドレスポリシーから、queue.news.sport 文字列で始まるすべてのアドレスが除外されます。

1. <broker_instance_dir>/etc/broker.xml 設定ファイルを開きます。

2. <amqp-connection> 要素を含む <broker connections> 要素を追加します。<amqp-connection> 要素で、リモートブローカーの接続詳細を指定し、フェデレーション設定に名前を割り当てます。以下に例を示します。

   <broker-connections>
     <amqp-connection uri="tcp://<__HOST__>:<__PORT__>" user="federation_user" password="federation_pwd" name="queue-federation-example">
     </amqp-connection>
   </broker-connections>

3. <federation> 要素を追加し、次のいずれかまたは両方を含めます。

   • リモートブローカーからローカルブローカーにメッセージをフェデレーションするための <local-queue-policy> 要素。
   • ローカルブローカーからリモートブローカーにメッセージをフェデレーションするための <remote-queue-policy> 要素。

   次の例は、ローカルキューポリシーを含む federation 要素を示しています。

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

   name

   キューポリシーの名前。すべてのキューポリシー名が、<broker-connections> 要素の <federation> 要素内で一意である必要があります。

   include

   アドレスと一致する address-match パターンと、ポリシーに含めるアドレスの特定のキューと一致する queue-match パターン。queue-match パラメーターには、address-match パラメーターと同様に、正確な名前を指定することも、ワイルドカード表現を使用してキューのセットを指定することもできます。上記の例では、すべてのアドレスの .remote という文字列に一致するキューが含まれます。これは address-match の値 # で表されます。

   exclude

   アドレスと一致する address-match パターンと、ポリシーから除外するアドレスの特定のキューと一致する queue-match パターン。queue-match パラメーターには、address-match パラメーターと同様に、正確な名前を指定することも、ワイルドカード表現を使用してキューのセットを指定することもできます。上記の例では、すべてのアドレスの .local という文字列に一致するキューが除外されます。これは address-match の値 # で表されます。

   priority-adjustment

   同じキュー上の他のローカルコンシューマーよりも優先度の値が低くなるように、フェデレーテッドコンシューマーの値を調整します。デフォルト値は -1 です。この値にすると、ローカルコンシューマーがフェデレーテッドコンシューマーよりも優先されます。

   include-federated

   このパラメーターの値を false に設定すると、設定は、すでにフェデレーションされたコンシューマー (つまりフェデレーションされたキューのコンシューマー) は統合しなおされません。これにより、対称トポロジーまたは閉ループトポロジーで、非フェデレーテッドコンシューマーが存在せず、メッセージがシステム内を際限なく流れるという状況が回避されます。

   閉ループトポロジーがない場合は、このパラメーターの値を true に設定できます。たとえば、3 つのブローカー、BrokerA、BrokerB、および BrokerC のチェーンがあり、プロデューサーが BrokerA のコンシューマーと BrokerC のコンシューマーがあるとします。この場合、BrokerB がコンシューマーを BrokerA にフェデレーションしなおす必要があります。

手順

1. <broker_instance_dir>/etc/broker.xml 設定ファイルを開きます。

2. <federation> 要素が含まれる新しい <federations > 要素を追加します。以下に例を示します。

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

   name

   フェデレーション設定の名前。この例では、名前はローカルブローカーの名前に対応します。

   user

   アップストリームブローカーに接続するための共有ユーザー名。

   password

   アップストリームブローカーに接続するための共有パスワード。

   注記

   ユーザーとパスワードの認証情報がリモートブローカーごとに異なる場合は、設定に追加する時にこれらのブローカーの認証情報を個別に指定できます。これは、この手順の後半で説明します。

3. federation 要素内に <address-policy> 要素を追加します。以下に例を示します。

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
           </address-policy>
   
       </federation>
   </federations>

   name

   アドレスポリシーの名前。ブローカーに設定されるアドレスポリシーはすべて一意の名前を指定する必要があります。

   auto-delete

   アドレスのフェデレーション時に、ローカルブローカーはリモートアドレスに永続キューを動的に作成します。auto-delete プロパティーの値は、ローカルブローカーの切断後にリモートキューを削除するかどうかを指定します。また、auto-delete-delay および auto- delete-message-count プロパティーの値も到達するかどうかを指定します。動的に作成されたキューのクリーンアップを自動化する場合に便利なオプションです。また、ローカルブローカーが長時間切断されている場合に、リモートブローカーでメッセージをビルドできないようにする場合にも便利なオプションです。ただし、接続されていない間にメッセージをローカルブローカーに対して常にキューに入れる必要がある場合、このオプションを false に設定します。これにより、ローカルブローカーでメッセージが失われないようにします。

   auto-delete-delay

   ローカルブローカーが切断されると、このプロパティーの値は、動的に作成されるリモートキューが自動的に削除されるまでの時間 (ミリ秒単位) を指定します。

   auto-delete-message-count

   ローカルブローカーが切断されると、このプロパティーの値は、キューが自動的に削除される前に動的に作成されたリモートキューにあるメッセージの最大数を指定します。

   enable-divert-bindings

   このプロパティーを true に設定すると、迂回バインディングは必要に応じてリッスンできます。アドレスポリシーに含まれるアドレスに一致するアドレスを持つ迂回バインディングがある場合、迂回の転送アドレスに一致するキューバインディングは要求を作成します。デフォルト値は false です。

   max-hops

   フェデレーション中にメッセージが実行できるホップの最大数。特定のトポロジーでは、このプロパティーに特定の値が必要です。これらの要件の詳細は、「アドレスフェデレーションの一般的なトポロジー」 を参照してください。

   transformer-ref

   トランスフォーマー設定の名前。フェデレーションされたメッセージ送信時にメッセージを変換する場合は、トランスフォーマー設定を追加できます。トランスフォーマー設定は、この手順の後半で説明します。

4. <address-policy> 要素内に、アドレスポリシーからアドレスを追加し、アドレスを除外するためのアドレス一致パターンを追加します。以下に例を示します。

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
       </federation>
   </federations>

   include

   この要素の address-match プロパティーの値は、アドレスポリシーに含めるアドレスを指定します。queue.bbc.new や queue.usatoday など、正確なアドレスを指定できます。または、ワイルドカード式を使用して一致するアドレスの セット を指定できます。前の例では、アドレスポリシーには、文字列 queue.news で始まるアドレス名が すべて 含まれます。

   exclude

   この要素の address-match プロパティーの値は、アドレスポリシーから除外するアドレスを指定します。正確なアドレス名を指定するか、ワイルドカード式を使用して一致するアドレスの セット を指定できます。上記の例では、アドレスポリシーは文字列 queue.news.sport で始まるすべてのアドレス名を除外します。

5. (オプション) federation 要素内に、カスタムトランスフォーマー実装を参照する transformer 要素を追加します。以下に例を示します。

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   name

   トランスフォーマー設定の名前。この名前は、ローカルブローカーで一意である必要があります。これは、アドレスポリシーの transformer-ref プロパティーの値として指定する名前です。

   class-name

   org.apache.activemq.artemis.core.server.transformer.Transformer インターフェイスを実装するユーザー定義クラスの名前。

   トランスフォーマーの transform() メソッドは、メッセージが送信される前にメッセージで呼び出されます。これにより、メッセージヘッダーまたはボディーをフェデレーションする前に変換できます。

   プロパティー

   特定のトランスフォーマー設定のキーと値のペアを保持するために使用されます。

6. federation 要素内に、upstream 要素を 1 つ以上追加します。各 upstream 要素は、リモートブローカーへの接続と、その接続に適用するポリシーを定義します。以下に例を示します。

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <upstream name="eu-east-1">
               <static-connectors>
                   <connector-ref>eu-east-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-address-federation"/>
           </upstream>
   
           <upstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-address-federation"/>
           </upstream>
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   static-connectors

   ローカルブローカーの broker.xml 設定ファイルの他の場所で定義される connector 要素を参照する connector-ref 要素のリストが含まれます。コネクターは、送信接続に使用するトランスポート (TCP、SSL、HTTP など) およびサーバー接続パラメーター (ホスト、ポートなど) を定義します。この手順の次のステップは、static-connectors 要素で参照されるコネクターを追加する方法を示しています。

   policy-ref

   アップストリームブローカーに適用されるダウンストリームブローカーに設定されたアドレスポリシーの名前。

   アップストリーム 要素に指定できる追加オプションを以下に示します。

   name

   アップストリームブローカー設定の名前。この例では、名前は eu-east-1 と eu-west-1 というアップストリームブローカーに対応します。

   user

   アップストリームブローカーへの接続の作成時に使用するユーザー名。指定のない場合は、federation 要素の設定に指定された共有ユーザー名が使用されます。

   password

   アップストリームブローカーへの接続の作成時に使用するパスワード。指定のない場合は、federation 要素の設定に指定された共有パスワードが使用されます。

   call-failover-timeout

   call-timeout と同様ですが、フェイルオーバーの試行中に呼び出しが行われる場合に使用されます。デフォルト値は -1 で、タイムアウトが無効であることを意味します。

   call-timeout

   ブロック呼び出しであるパケットを送信すると、フェデレーション接続がリモートブローカーからの応答を待つ時間 (ミリ秒単位)。この時間が経過すると、接続によって例外が発生します。デフォルト値は 30000 です。

   check-period

   フェデレーション接続の健常性を確認するために、ローカルブローカがリモートブローカに送信する連続した“keep-alive"メッセージ間の期間 (ミリ秒)。フェデレーション接続が正常である場合、リモートブローカーは各キープアライブメッセージに応答します。接続が正常でないと、ダウンストリームブローカーがアップストリームブローカーから応答を受信できない場合に、サーキットブレーカー と呼ばれるメカニズムを使用してフェデレーションされたコンシューマーをブロックします。詳細は、circuit-breaker-timeout パラメーターの説明を参照してください。check-period パラメーターのデフォルト値は 30000 です。

   circuit-breaker-timeout

   ダウンストリームとアップストリームブローカー間の単一の接続は、多くのフェデレーションされたキューとアドレスコンシューマーによって共有される可能性があります。ブローカー間の接続が失われた場合、フェデレーションされた各コンシューマーは同時に再接続を試みる可能性があります。これを回避するには、サーキットブレーカー と呼ばれるメカニズムはコンシューマーをブロックします。指定したタイムアウト値が経過すると、サーキットブレーカーは接続を再送します。成功すると、コンシューマーはブロックされません。それ以外の場合は、サーキットブレーカーが再度適用されます。

   connection-ttl

   リモートブローカーからのメッセージを受信しなくなった場合に、フェデレーション接続が存続する時間 (ミリ秒単位)。デフォルト値は 60000 です。

   discovery-group-ref

   アップストリームブローカーへの接続に静的コネクターを定義する代わりに、この要素を使用して broker.xml 設定ファイルの別の場所で設定済みの検出グループを指定できます。具体的には、この要素の discovery-group-name プロパティーの値として、既存の検出グループを指定します。検出グループの詳細は、「ブローカー検出メソッド」 を参照してください。

   ha

   アップストリームブローカーへの接続に対して、高可用性が有効であるかどうかを指定します。このパラメーターの値を true に設定すると、ローカルブローカーはアップストリームクラスターで利用可能なブローカーに接続でき、ライブアップストリームブローカーがシャットダウンすると、バックアップブローカーに自動フェイルオーバーされます。デフォルト値は false です。

   initial-connect-attempts

   ダウンストリームブローカーがアップストリームブローカーに接続するようにする初期試行の数。接続を確立せずにこの値に達すると、アップストリームブローカーは永続的にオフラインとみなされます。ダウンストリームブローカーは、メッセージをアップストリームブローカーにルーティングしなくなりました。デフォルト値は -1 で、制限がないことを意味します。

   max-retry-interval

   リモートブローカーへの接続に失敗した場合に後続の再接続試行の間隔 (ミリ秒単位)。デフォルト値は 2000 です。

   reconnect-attempts

   接続が失敗した場合に、ダウンストリームブローカーがアップストリームブローカーへの再接続を試行する回数。接続が再確立されていない状態でこの値に達すると、アップストリームブローカーは永続的にオフラインとみなされます。ダウンストリームブローカーは、メッセージをアップストリームブローカーにルーティングしなくなりました。デフォルト値は -1 で、制限がないことを意味します。

   retry-interval

   リモートブローカーへの接続に失敗した場合に、後続の再接続試行の間隔 (ミリ秒単位)。デフォルト値は 500 です。

   retry-interval-multiplier

   retry-interval パラメーターの値に適用される乗率。デフォルト値は 1 です。

   share-connection

   同じブローカーにダウンストリーム接続とアップストリーム接続の両方が設定されている場合には、ダウンストリーム設定とアップストリーム設定の両方がこのパラメーターの値を true に設定している限り、同じ接続が共有されます。デフォルト値は false です。

7. ローカルブローカーで、コネクターをリモートブローカーに追加します。これらは、フェデレーションされたアドレス設定の static-connectors 要素で参照されるコネクターです。以下に例を示します。

   <connectors>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>

手順

1. ローカルブローカーで、<broker_instance_dir>/etc/broker.xml 設定ファイルを開きます。

2. <federation> 要素が含まれる <federations > 要素を追加します。以下に例を示します。

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
       </federation>
   </federations>

3. アドレスポリシー設定を追加します。以下に例を示します。

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
       </federation>
     ...
   </federations>

4. 送信前にメッセージを変換する場合は、トランスフォーマー設定を追加します。以下に例を示します。

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

5. 各リモートブローカーに ダウンストリーム 要素を追加します。以下に例を示します。

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <downstream name="eu-east-1">
                   <static-connectors>
                       <connector-ref>eu-east-connector1</connector-ref>
                   </static-connectors>
                   <upstream-connector-ref>netty-connector</upstream-connector-ref>
                   <policy ref="news-address-federation"/>
           </downstream>
   
           <downstream name="eu-west-1" >
                   <static-connectors>
                       <connector-ref>eu-west-connector1</connector-ref>
                   </static-connectors>
                   <upstream-connector-ref>netty-connector</upstream-connector-ref>
                   <policy ref="news-address-federation"/>
           </downstream>
   
           <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

   上記の設定で示されているように、リモートブローカーはローカルブローカーのダウンストリームであると見なされます。ダウンストリームブローカーは、設定の接続情報を使用して、ローカル (アップストリーム) ブローカーへ再度接続します。

6. ローカルブローカーで、ローカルブローカーおよびリモートブローカーによって使用されるコネクターとアクセプターを追加して、フェデレーション接続を確立します。以下に例を示します。

   <connectors>
      <connector name="netty-connector">tcp://localhost:61616</connector>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>
   
   <acceptors>
      <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor>
   </acceptors>

   connector name="netty-connector"

   ローカルブローカーがリモートブローカーに送信するコネクター設定。リモートブローカーはこの設定を使用してローカルブローカーに接続し直します。

   connector name="eu-west-1-connector", connector name="eu-east-1-connector"

   リモートブローカーへのコネクター。ローカルブローカーはこれらのコネクターを使用してリモートブローカーに接続し、リモートブローカーがローカルブローカーに接続するために必要な設定を共有します。

   acceptor name="netty-acceptor"

   ローカルブローカーに接続するためにリモートブローカーによって使用されるコネクターに対応するローカルブローカーのアクセプター。

手順

1. <broker_instance_dir>/etc/broker.xml 設定ファイルを開きます。

2. 新しい <federations> 要素に、<federation> 要素を追加します。以下に例を示します。

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

   name

   フェデレーション設定の名前。この例では、名前はダウンストリームブローカーの名前に対応します。

   user

   アップストリームブローカーに接続するための共有ユーザー名。

   password

   アップストリームブローカーに接続するための共有パスワード。

   注記
   • ユーザーとパスワードの認証情報がアップストリームブローカーごとに異なる場合は、設定に追加する時にこれらのブローカーの認証情報を個別に指定できます。これは、この手順の後半で説明します。

3. federation 要素内に <queue-policy> 要素を追加します。<queue-policy> 要素のプロパティー値を指定します。以下に例を示します。

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
           </queue-policy>
   
       </federation>
   </federations>

   name

   キューポリシーの名前。ブローカーに設定されるキューポリシーはすべて一意の名前である必要があります。

   include-federated

   このプロパティーの値を false に設定すると、設定は、すでにフェデレーションされたコンシューマー (つまりフェデレーションされたキューのコンシューマー) は統合しなおされません。これにより、対称または閉ループトポロジーで、フェデレーションされていないコンシューマーが存在せず、メッセージがシステム内を無限に流れる状況を回避できます。

   閉ループトポロジーが ない 場合は、このプロパティーの値を true に設定できます。たとえば、3 つのブローカー、BrokerA、BrokerB、および BrokerC のチェーンがあり、プロデューサーが BrokerA のコンシューマーと BrokerC のコンシューマーがあるとします。この場合、BrokerB がコンシューマーを BrokerA に再フェデレーションする 必要があります。

   priority-adjustment

   コンシューマーがキューに接続すると、その優先度は、アップストリーム (フェデレーションされた) コンシューマーの作成時に優先順位が使用されます。フェデレーションされたコンシューマーの優先度は、priority-adjustment プロパティーの値で調整します。このプロパティーのデフォルト値は -1 です。これにより、負荷分散時にローカルコンシューマーがフェデレーションされたコンシューマーよりも優先されます。ただし、必要に応じて優先度の調整の値を変更できます。

   優先度の調整によって、フェデレーテッドコンシューマーに移動するメッセージが多すぎるためにブローカー間でメッセージが行き来するのを防げない場合は、フェデレーテッドコンシューマーに移動するメッセージのバッチサイズを制限できます。バッチサイズを制限するには、フェデレーテッドコンシューマーの接続 URI の consumerWindowSize 値を 0 に設定します。

   tcp://<host>:<port>?consumerWindowSize=0

   consumerWindowSize パラメーターが 0 に設定されている場合、AMQ Broker は、一致するアドレスのアドレス設定の defaultConsumerWindowSize 属性値を使用して、ブローカー間を移動できるメッセージのバッチサイズを決定します。defaultConsumerWindowSize 属性のデフォルト値は 1048576 バイトです。

   transformer-ref

   トランスフォーマー設定の名前。フェデレーションされたメッセージ送信時にメッセージを変換する場合は、トランスフォーマー設定を追加できます。トランスフォーマー設定は、この手順の後半で説明します。

4. <queue-policy> 要素内に、キューポリシーからアドレスを追加し、除外する address-matching パターンを追加します。以下に例を示します。

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
       </federation>
   </federations>

   include

   この要素の address-match プロパティーの値は、キューポリシーに含めるアドレスを指定します。queue.bbc.new や queue.usatoday など、正確なアドレスを指定できます。または、ワイルドカード式を使用して一致するアドレスの セット を指定できます。上記の例では、アドレスポリシーには文字列 queue.news で始まるすべてのアドレス名も含まれています。

   address-match プロパティーと組み合わせて、queue-match プロパティーを使用して、キューポリシーにこれらのアドレスに特定のキューを含めることができます。address-match プロパティーと同様に、正確なキュー名を指定することも、ワイルドカード式を使用して 一連 のキューを指定することもできます。上記の例では、番号記号 (#) のワイルドカード文字は、各アドレスまたはアドレスセットにある すべて のキューがキューポリシーに含まれることを示しています。

   exclude

   この要素の address-match プロパティーの値は、キューポリシーから除外するアドレスを指定します。正確なアドレスを指定するか、ワイルドカード式を使用して一致するアドレスの セット を指定できます。上記の例では、数字記号 (#) ワイルドカード文字は、全 アドレスの queue-match プロパティーと一致するキューがすべて除外されることを意味します。この場合、.local という文字列で終了するキューは除外されます。これは、特定のキューがローカルキューとして保持され、フェデレーションされていないことを示しています。

5. federation 要素内に、カスタムトランスフォーマー実装を参照する transformer 要素を追加します。以下に例を示します。

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   name

   トランスフォーマー設定の名前。この名前は、対象となるブローカーで一意でなければなりません。この名前は、アドレスポリシーの transformer-ref プロパティーの値として指定します。

   class-name

   org.apache.activemq.artemis.core.server.transformer.Transformer インターフェイスを実装するユーザー定義クラスの名前。

   トランスフォーマーの transform() メソッドは、メッセージが送信される前にメッセージで呼び出されます。これにより、メッセージヘッダーまたはボディーをフェデレーションする前に変換できます。

   プロパティー

   特定のトランスフォーマー設定のキーと値のペアを保持するために使用されます。

6. federation 要素内に、upstream 要素を 1 つ以上追加します。各 upstream 要素は、アップストリームブローカー接続と、その接続に適用するポリシーを定義します。以下に例を示します。

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <upstream name="eu-east-1">
               <static-connectors>
                   <connector-ref>eu-east-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-queue-federation"/>
           </upstream>
   
           <upstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-queue-federation"/>
           </upstream>
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   static-connectors

   ローカルブローカーの broker.xml 設定ファイルの他の場所で定義される connector 要素を参照する connector-ref 要素のリストが含まれます。コネクターは、送信接続に使用するトランスポート (TCP、SSL、HTTP など) およびサーバー接続パラメーター (ホスト、ポートなど) を定義します。以下の手順は、フェデレーションされたキュー設定の static-connectors 要素で参照されるコネクターを追加する方法を示しています。

   policy-ref

   アップストリームブローカーに適用されるダウンストリームブローカーに設定されたキューポリシーの名前。

   アップストリーム 要素に指定できる追加オプションを以下に示します。

   name

   アップストリームブローカー設定の名前。この例では、名前は eu-east-1 と eu-west-1 というアップストリームブローカーに対応します。

   user

   アップストリームブローカーへの接続の作成時に使用するユーザー名。指定のない場合は、federation 要素の設定に指定された共有ユーザー名が使用されます。

   password

   アップストリームブローカーへの接続の作成時に使用するパスワード。指定のない場合は、federation 要素の設定に指定された共有パスワードが使用されます。

   call-failover-timeout

   call-timeout と同様ですが、フェイルオーバーの試行中に呼び出しが行われる場合に使用されます。デフォルト値は -1 で、タイムアウトが無効であることを意味します。

   call-timeout

   ブロック呼び出しであるパケットを送信すると、フェデレーション接続がリモートブローカーからの応答を待つ時間 (ミリ秒単位)。この時間が経過すると、接続によって例外が発生します。デフォルト値は 30000 です。

   check-period

   フェデレーション接続の健常性を確認するために、ローカルブローカがリモートブローカに送信する連続した“keep-alive"メッセージ間の期間 (ミリ秒)。フェデレーション接続が正常である場合、リモートブローカーは各キープアライブメッセージに応答します。接続が正常でないと、ダウンストリームブローカーがアップストリームブローカーから応答を受信できない場合に、サーキットブレーカー と呼ばれるメカニズムを使用してフェデレーションされたコンシューマーをブロックします。詳細は、circuit-breaker-timeout パラメーターの説明を参照してください。check-period パラメーターのデフォルト値は 30000 です。

   circuit-breaker-timeout

   ダウンストリームとアップストリームブローカー間の単一の接続は、多くのフェデレーションされたキューとアドレスコンシューマーによって共有される可能性があります。ブローカー間の接続が失われた場合、フェデレーションされた各コンシューマーは同時に再接続を試みる可能性があります。これを回避するには、サーキットブレーカー と呼ばれるメカニズムはコンシューマーをブロックします。指定したタイムアウト値が経過すると、サーキットブレーカーは接続を再送します。成功すると、コンシューマーはブロックされません。それ以外の場合は、サーキットブレーカーが再度適用されます。

   connection-ttl

   リモートブローカーからのメッセージを受信しなくなった場合に、フェデレーション接続が存続する時間 (ミリ秒単位)。デフォルト値は 60000 です。

   discovery-group-ref

   アップストリームブローカーへの接続に静的コネクターを定義する代わりに、この要素を使用して broker.xml 設定ファイルの別の場所で設定済みの検出グループを指定できます。具体的には、この要素の discovery-group-name プロパティーの値として、既存の検出グループを指定します。検出グループの詳細は、「ブローカー検出メソッド」 を参照してください。

   ha

   アップストリームブローカーへの接続に対して、高可用性が有効であるかどうかを指定します。このパラメーターの値を true に設定すると、ローカルブローカーはアップストリームクラスターで利用可能なブローカーに接続でき、ライブアップストリームブローカーがシャットダウンすると、バックアップブローカーに自動フェイルオーバーされます。デフォルト値は false です。

   initial-connect-attempts

   ダウンストリームブローカーがアップストリームブローカーに接続するようにする初期試行の数。接続を確立せずにこの値に達すると、アップストリームブローカーは永続的にオフラインとみなされます。ダウンストリームブローカーは、メッセージをアップストリームブローカーにルーティングしなくなりました。デフォルト値は -1 で、制限がないことを意味します。

   max-retry-interval

   リモートブローカーへの接続に失敗した場合に後続の再接続試行の間隔 (ミリ秒単位)。デフォルト値は 2000 です。

   reconnect-attempts

   接続が失敗した場合に、ダウンストリームブローカーがアップストリームブローカーへの再接続を試行する回数。接続が再確立されていない状態でこの値に達すると、アップストリームブローカーは永続的にオフラインとみなされます。ダウンストリームブローカーは、メッセージをアップストリームブローカーにルーティングしなくなりました。デフォルト値は -1 で、制限がないことを意味します。

   retry-interval

   リモートブローカーへの接続に失敗した場合に、後続の再接続試行の間隔 (ミリ秒単位)。デフォルト値は 500 です。

   retry-interval-multiplier

   retry-interval パラメーターの値に適用される乗率。デフォルト値は 1 です。

   share-connection

   同じブローカーにダウンストリーム接続とアップストリーム接続の両方が設定されている場合には、ダウンストリーム設定とアップストリーム設定の両方がこのパラメーターの値を true に設定している限り、同じ接続が共有されます。デフォルト値は false です。

7. ローカルブローカーで、コネクターをリモートブローカーに追加します。これらは、フェデレーションされたアドレス設定の static-connectors 要素で参照されるコネクターです。以下に例を示します。

   <connectors>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>

   注記

   サイズの大きいメッセージをフェデレーション接続経由で送受信する場合は、フェデレーション接続に使用されるコネクターで consumerWindowSize パラメーターを -1 に設定します。consumerWindowSize パラメーターを -1 に設定すると、このパラメーターに制限が設定されず、接続間でサイズの大きいメッセージが送受信されるようになります。以下に例を示します。

   <connectors>
      <connector name="eu-west-1-connector">tcp://localhost:61616?consumerWindowSize=-1</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617?consumerWindowSize=-1</connector>
   </connectors>

   サイズの大きいメッセージの詳細は、8章大きなメッセージの処理 を参照してください。

手順

1. <broker_instance_dir>/etc/broker.xml 設定ファイルを開きます。

2. <federation> 要素が含まれる <federations > 要素を追加します。以下に例を示します。

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

3. キューポリシー設定を追加します。以下に例を示します。

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
       </federation>
     ...
   </federations>

4. 送信前にメッセージを変換する場合は、トランスフォーマー設定を追加します。以下に例を示します。

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

5. 各リモートブローカーに ダウンストリーム 要素を追加します。以下に例を示します。

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <downstream name="eu-east-1">
               <static-connectors>
                   <connector-ref>eu-east-connector1</connector-ref>
               </static-connectors>
               <upstream-connector-ref>netty-connector</upstream-connector-ref>
               <policy ref="news-address-federation"/>
           </downstream>
   
           <downstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <upstream-connector-ref>netty-connector</upstream-connector-ref>
               <policy ref="news-address-federation"/>
           </downstream>
   
           <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.myorg.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

   上記の設定で示されているように、リモートブローカーはローカルブローカーのダウンストリームであると見なされます。ダウンストリームブローカーは、設定の接続情報を使用して、ローカル (アップストリーム) ブローカーへ再度接続します。

6. ローカルブローカーで、ローカルブローカーおよびリモートブローカーによって使用されるコネクターとアクセプターを追加して、フェデレーション接続を確立します。以下に例を示します。

   <connectors>
      <connector name="netty-connector">tcp://localhost:61616</connector>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>
   
   <acceptors>
      <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor>
   </acceptors>

   connector name="netty-connector"

   ローカルブローカーがリモートブローカーに送信するコネクター設定。リモートブローカーはこの設定を使用してローカルブローカーに接続し直します。

   connector name="eu-west-1-connector" , connector name="eu-east-1-connector"

   リモートブローカーへのコネクター。ローカルブローカーはこれらのコネクターを使用してリモートブローカーに接続し、リモートブローカーがローカルブローカーに接続するために必要な設定を共有します。

   acceptor name="netty-acceptor"

   ローカルブローカーに接続するためにリモートブローカーによって使用されるコネクターに対応するローカルブローカーのアクセプター。

   注記

   サイズの大きいメッセージをフェデレーション接続経由で送受信する場合は、フェデレーション接続に使用されるコネクターで consumerWindowSize パラメーターを -1 に設定します。consumerWindowSize パラメーターを -1 に設定すると、このパラメーターに制限が設定されず、接続間でサイズの大きいメッセージが送受信されるようになります。以下に例を示します。

   <connectors>
      <connector name="eu-west-1-connector">tcp://localhost:61616?consumerWindowSize=-1</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617?consumerWindowSize=-1</connector>
   </connectors>

   サイズの大きいメッセージの詳細は、8章大きなメッセージの処理 を参照してください。