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

手順

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 です。これにより、負荷分散時にローカルコンシューマーがフェデレーションされたコンシューマーよりも優先されます。ただし、必要に応じて優先順位の調整の値を変更できます。

手順

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"

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