4.21.8. アップストリームキューフェデレーションの設定

手順

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

   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.foo.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.foo.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>