For distributed platformsFor z/OS platforms[17.0.0.1 and later]

Liberty 動的ルーティングのルーティング・ルールの構成

動的ルーティングのルーティング・ルール機能によって、要求情報に基づいて特別なルーティング動作を行うよう要求を選択できます。

始める前に

集合コントローラーで動的ルーティングを使用可能にします。Liberty 集合に対する動的ルーティングのセットアップのステップに従います。

ヒント: ルーティング・ルールを使用して複数の集合へルーティングする場合、各集合にそれぞれ異なる名前が付いている必要があります。集合に名前を付けるには、 collective create コマンドを実行するときに --collectiveName オプションを使用します。既に作成済みの集合の場合は、 <dynamicRouting> XML エレメントの connectorClusterName プロパティーを使用して集合に論理名を付けることができます。connectorClusterName プロパティーが指定されていると、その値は、--collectiveName オプションで指定された collectiveName よりも優先されます。複数の Liberty 集合に対する動的ルーティングのセットアップを参照してください。

このタスクについて

デフォルトでは、動的ルーティングは、要求を処理できるすべてのサーバーで要求負荷のバランスを取ります。ルーティング・ルールを構成してデフォルトの動作をオーバーライドし、 ルーティング・ルールが要求を特定のサーバー・リソースにルーティングしたり、要求をリダイレクトしたり、要求を拒否したりするようにできます。

注: 集合内のすべての集合コントローラーは、動的ルーティング・サービスを介して同じルーティング・ルール・セットを提供する必要があります。すべてのコントローラーが同じルーティング・ルールを使用することを確実にするには、ルーティング・ルールを含んでいる .xml ファイルを、いずれか 1 つのコントローラーの configDropins/defaults ディレクトリーに追加します。詳しくは、レプリカ間での構成の自動共有を参照してください。

手順

  1. コントローラーの server.xml ファイルで、<dynamicRouting> エレメントの子として <routingRules> エレメントを追加します。

    <routingRules> エレメントの webServers 属性を指定します。各 <routingRules> エレメントは、 ルールが公開される Web サーバーの適用可能なセットを定義できます。Web サーバーが動的ルーティング・サービスに接続されると、サービスはルールをその Web サーバーに配信します。Web サーバーが指定されていない場合、 サービスは接続されているすべての Web サーバーにルールを配信します。複数の Web サーバーを指定する場合は、 区切り文字としてコンマ (,) を使用してください。webServers 属性の値を * にして指定されたルールは、すべての Web サーバーに配信されます。 以下の例を参照してください。

    <dynamicRouting>
       <routingRules webServers="webserver1,webserver2">
       ...
       </routingRules>
    </dynamicRouting>
    <routingRules> エレメントの overrideAffinity 属性を指定します。デフォルトでは、特定のサーバーへのアフィニティーが指定された要求はそのサーバーに送信されます (要求が一致するルーティング・ルールがあり、そのルールには宛先としてそのアフィニティー・サーバーが含まれていない場合であってもそうなります)。overrideAffinity プロパティーが true に設定されていると、 一致するルールに含まれている宛先を選択することが、アフィニティー・サーバーを選択することよりも優先されます。一致するルールをアフィニティー・サーバーが満たす場合は、 アフィニティー・サーバーがエンドポイントのフェイルオーバー・セット中にあってもアフィニティー・サーバーが選択されます。overrideAffinity プロパティーは、すべてのルーティング・ルールに適用され、個別ルールに設定することはできません。
    <dynamicRouting>
       <routingRules webServers="webserver1" 
    overrideAffinity=”true”>
       ...
       </routingRules>
    </dynamicRouting>
  2. <routingRules> エレメントの子として <routingRule> エレメントを追加します。
    1. ルーティング・ルールの order 属性を指定し、値を整数に設定します。 order 属性は必須です。ルールは、order が最低のものから最高のものへと順に評価されます。同じ order 属性が割り当てられたルールが複数ある場合、 最初に検出されたルールが公開され、同じ order 属性を持つ他のすべてのルールは破棄されます。ルールの order 数値は間をあけて指定するようにして、将来のルール用に空きを確保しておくことは有効な慣例です。
    2. ルーティング・ルールの matchExpression 属性を指定します。一致する着信要求を検出できるような式に設定します。一致式は、 いくつかの固定オペランドとオペレーターを組み合わせたものです。AND および OR 演算子を使用して、オペランドとオペレーターの複数のセットを結合できます。
    <dynamicRouting>
       <routingRules webServers="webserver1,webserver2">
          <routingRule order="100" matchExpression="URI LIKE'/myapp%'">
          ...
          </routingRule>
       </routingRules>
    </dynamicRouting>
    表 1. matchExpression のオペランド. 1 つの matchExpression 定義に 1 つのオペランドを含めます。
    オペランド 構文 説明
    クライアント IPV4 clientipv4 Internet Protocol version 4 (IPv4) ドット付きクワッドのアドレス・タイプ n.n.n.n を使用した、クライアントの IP アドレス。
    クライアント IPV6 clientipv6 クライアント・コンピューターの Request for Comments 1924 (RFC 1924) に準じた、Internet Protocol バージョン 6 (IPv6) 128 ビット・アドレス・タイプ x:x:x:x:x:x:x:x
    Cookie 名 cookie$name Cookie (クッキー) 名。

    例えば、式 cookie$My_Cookie_Name='My_Cookie_Value' は、要求をテストして、My_Cookie_Name という名前で、値が My_Cookie_Value の Cookie が含まれているかどうかを確認します。ある特定の Cookie が存在するかどうかをテストするには、 次の式のいずれかを使用します。

    cookie$MyCookieName IS NOT NULL 
    cookie$MyCookieName IS NULL
    ヘッダー名 header$name ヘッダー名と値。

    例えば、式 header$Host='localhost' は、要求をテストして、値が locahost の HTTP ホスト・ヘッダーが含まれているかどうかを確認します。ホスト・ヘッダーが存在するかどうかをテストするには、 次の式のいずれかを使用します。

    header$Host IS NOT NULL 
    header$Host IS NULL
    割合 percentage$val 割合オペランドは、特定の確率 (パーセンテージ) で true に評価されます。

    例えば、percentage$50 は、時間のパーセンテージが平均で 50% の場合に true に評価されます。

    照会パラメーター queryparm$name 照会パラメーターの名前と値。

    例えば、式 queryparm$timezone='EST' は、要求をテストして、名前が timezone、値が EST の HTTP 照会パラメーターが含まれているかどうかを確認します。照会パラメーターが存在するかどうかをテストするには、 次の式のいずれかを使用します。

    queryparm$timezone IS NOT NULL 
    queryparm$timezone IS NULL
    URI uri Uniform Resource Identifier
    仮想ホスト virtualhost 要求の仮想ホスト・ターゲット
    仮想ポート numeric 要求の仮想ポート・ターゲット
    表 2. matchExpression のオペレーター. 必要に応じて、1 つの matchExpression 定義に 1 つのオペレーターを含めます。
    オペレーター 構文 説明
    等しい = 等価演算子は、大/小文字を区別した一致を表します。
    等しい - 大/小文字を無視 EQUALSIGNORECASE ストリングの大/小文字が無視される点を除いて、'String = String' と同じです。例えば、'ABC' EQUALSIGNORECASE 'abc'true と評価され、('ABC' = 'abc')false と評価されます。
    IN IN 単一の式で複数の値を持つオペランドを表します。例えば、port というオペランドで、port の値として可能な値が、整数 9080、9090、および 9091 のいずれかまたはすべてであることを表す場合、 式フラグメントは port IN (9080,9090,9091) です。

    括弧内の値の表現方法はデータ型に基づきます。例えば、 port が整数である場合、正しい構文は引用符なしの値です。port がストリングの場合、正しい構文は port IN ('9080','9090','9091') です。

    Null でない IS NOT NULL 指定されたオペランドが存在する場合に true と評価されます。
    Null である IS NULL 指定されたオペランドが存在しない場合に true と評価されます。
    次に類似 LIKE ストリング・オペランド値のパターン・マッチングを表します。値には、パターン・マッチングを開始する位置にワイルドカード文字の % 記号が含まれている必要があります。以下に例を示します。
    • host LIKE %blanca 式は、blanca という語または blanca で終わるすべての語に一致します。
    • host LIKE blanca% 式は、blanca という語または blanca で始まるすべての語に一致します。
    • host LIKE %blanca% 式は、blanca という語または blanca を含むすべての語に一致します。
    次に類似 - 大/小文字を無視 LIKEIGNORECASE ストリングの大/小文字が無視される点を除いて、'string LIKE string' と同じです。
    次に類似 - IN LIKEIN あるストリングがストリングのリスト中に存在するかどうかを評価します。例えば、string likein (string1%, string2%, string3%) は、string が括弧内の 1 つ以上のストリングと一致すれば true と評価されます。この例では、括弧内に 3 つの string 値が含まれています。
  3. ルーティング・ルールのアクション・タイプを指定します。

    可能なアクション・タイプは、permitActionredirectAction、および rejectAction の 3 つです。ルーティング・ルールごとに、3 つのアクション・タイプのうち 1 つのみを指定します。

    • 識別されたエンドポイントに要求をルーティングするには、permitAction アクション・タイプを指定します。
      1. <permitAction> エレメントを <routingRule> エレメントに追加します。
      2. オプションで、<permitAction> エレメントに allowMaintenanceModeServers 属性を追加して、ルールに一致する要求が保守モードのサーバーに送信されるかどうかを指定します。この属性のデフォルト値は false です。この属性が true に設定されている場合、このルールに一致する要求は保守モードのサーバーに送信可能です。
      3. <permitAction> エレメントに 1 つ以上の <loadBalanceEndPoints> エレメントを追加します。

        1 つの <permitAction> エレメントに複数の <loadBalanceEndPoints> エレメントがある場合、 最初の <loadBalanceEndPoints> エレメントが宛先の 1 次セットとなります。後続のすべての <loadBalanceEndPoints> エレメントはフェイルオーバー宛先となります。<loadBalanceEndPoints> エレメントが定義されている順序が、フェイルオーバー優先順位を決定します。

      4. <loadBalanceEndPoints> エレメントに 1 つ以上の <endpoint> エレメントを追加します。
      5. <endpoint> エレメントに destination 属性を追加します。 destination 属性をサーバー・タイプまたはクラスター・タイプのいずれかに設定します。

        サーバー・タイプのエンドポイントを指定するには、 server= の後に、4 つのパートをコンマで区切ったサーバー仕様を指定します。

        <endpoint destination="server=collective_name,host_name,wlp.user.dir,server_name"/>
        • collective_name は、サーバーがメンバーである集合の名前です。
        • host_name は、ホスト・アドレスです。
        • wlp.user.dir は、サーバーが定義されているホスト・システム上の Liberty ユーザー・ディレクトリーです。ここでは ${wlp.user.dir} 変数を使用できることもありますが、それが適切でない場合もあります。この server.xml が評価されるとき、${wlp.user.dir} の値は、コントローラー・サーバーが定義されているディレクトリーです。これは、メンバー・サーバーが定義されているのと同じディレクトリーではない場合があります。
        • server_name はサーバー名です。

        クラスター・タイプのエンドポイントを指定するには、cluster= の後に、2 つのパートをコンマで区切ったサーバー仕様を指定します。

        <endpoint destination="cluster=collective_name,cluster_name"/>
        • collective_name は、クラスターが定義されている集合の名前です。
        • cluster_name はクラスター名です。

        サーバーまたはクラスターの宛先仕様のすべてのパートで、どのストリングとも一致するワイルドカード文字 (*) を使用できます。ルーティング・ルールを使用して複数の集合へルーティングする場合、各集合にそれぞれ異なる名前が付いている必要があります。<dynamicRouting> エレメントの connectorClusterName 属性が指定されている場合、 集合名は connectorClusterName 属性の値です。<dynamicRouting>connectorClusterName 属性が指定されていない場合、 集合名は、collective create コマンドの実行時に --collectiveName オプションに使用された値です。connectorClusterName 属性が指定されておらず、 --collectiveName オプションも使用されていない場合、集合名は defaultCollective です。

      以下の例は、サーバー・タイプのエンドポイントが指定された <permitAction> エレメントを示します。

      <dynamicRouting maxRetries="5" retryInterval="10000">
         <routingRules webServers="myWebServer">
            <routingRule order="100" matchExpression="URI LIKE '/myapp%'">
               <permitAction>
                  <loadBalanceEndPoints>
                     <endpoint destination="server=collective1,myhost,/opt/IBM/liberty/wlp/usr,member1"/>
                  </loadBalanceEndPoints>
               </permitAction>
            </routingRule>
         </routingRules>
      </dynamicRouting>
    • 別のロケーションに要求をルーティングするには、redirectAction アクション・タイプを指定します。
      1. <redirectAction> エレメントを <routingRule> エレメントに追加します。
      2. <redirectAction> エレメントに location 属性を追加します。location 属性を、要求の新しい宛先に設定します。

      次の例は、<redirectAction> エレメントを示します。

      <dynamicRouting maxRetries="5" retryInterval="10000">
         <routingRules webServers="myWebServer">
            <routingRule order="200" matchExpression="URI LIKE '/myapp%'">
               <redirectAction location="http://some.other.destination" />
            </routingRule>
         </routingRules>
      </dynamicRouting>
    • 特定の応答コードで要求を拒否するには、rejectAction アクション・タイプを指定します。
      1. <rejectAction> エレメントを <routingRule> エレメントに追加します。
      2. <rejectAction> エレメントに code 属性を追加します。code 属性を、要求がルールに一致した場合に使用する HTTP 応答コードに設定します。コードは、Web サーバーでサポートされるエラー・コードでなければなりません。

      次の例は、<rejectAction> エレメントを示します。

      <dynamicRouting maxRetries="5" retryInterval="10000">
         <routingRules webServers="myWebServer">
            <routingRule order="300" matchExpression="URI LIKE '/myapp%'">
               <rejectAction code="503" />
            </routingRule>
         </routingRules>
      </dynamicRouting>

タスクの結果

ルールが定義された後、Web サーバーが動的ルーティング・サービスに接続されると、 その Web サーバーと関連付けられたルールと、すべての Web サーバーと関連付けられたルールが配信されます。Web サーバーは、 それらのルール内で見つかった一致式に対して要求を突き合わせます。式は、ルールの order に従って、最低から最高への順に評価されます。一致する式を含む最初のルールが使用されます。そのルールと関連付けられたアクションによって、 要求の処理方法が決まります。一致するルールがない場合、要求を処理できるすべてのサーバーで要求負荷のバランスが取られます。

デフォルトでは、要求がセッション・アフィニティーを持つ場合、サーバーの選択は、アフィニティーに基づいて行われます。アフィニティー・サーバーが見つかった場合、 そのサーバーが選択され、ルーティング・ルールは評価されません。ルーティング・ルールによってアフィニティー選択をオーバーライドできるようにするには、server.xml ファイルの <routingRules> エレメントに overrideAffinity 属性を追加します。

次の例では、複数のルールが結合されています。

<dynamicRouting>
   <routingRules webServers="myWebServer">
      <routingRule order="100" matchExpression="URI LIKE '/myapp%'">
         <permitAction>
            <loadBalanceEndPoints>
               <endpoint destination="server=collective1,*,*,member1"/>
            </loadBalanceEndPoints>
            <loadBalanceEndPoints>
               <endpoint destination="server=collective2,*,*,member1"/>
            </loadBalanceEndPoints>
         </permitAction>
      </routingRule>
      <routingRule order="200" matchExpression="uri like '/AppX%' AND queryparm$test = 'true'">
         <permitAction allowMaintenanceModeServers="true">
            <loadBalanceEndPoints>
               <endpoint destination="cluster=collective1,clusterB"/>
               <endpoint destination="cluster=collective2,clusterB"/>
            </loadBalanceEndPoints>
         </permitAction>
      </routingRule>
      <routingRule order="300" matchExpression=" uri like '/AppX%' ">
         <permitAction>
            <loadBalanceEndPoints>
               <endpoint destination="cluster=collective1,clusterA"/>
               <endpoint destination="cluster=collective2,clusterA"/>
            </loadBalanceEndPoints>
         </permitAction>
      </routingRule>
      <routingRule order="400" matchExpression="URI LIKE '/myoldapp'">
         <redirectAction location="http://mysite/mynewapp" />
      </routingRule>
      <routingRule order="500" matchExpression="URI LIKE '/myveryoldapp'">
         <rejectAction code="503" />
      </routingRule>
   </routingRules>
 </dynamicRouting>

-order 100 のルーティング・ルールは、/AppX に対する要求がルーティングされる宛先を、2 つの集合の 2 つの特定のクラスターに制限します。

–order 200 のルーティング・ルールは、1 つのエンドポイント・セットから別のセットへのフェイルオーバーを有効にする方法を示しています。ルール 200 は、式に一致するすべての要求を、要求を処理できる collective1 内の任意のサーバーにルーティングします。要求を処理できる collective1 内のすべてのサーバーが使用不可の場合、要求を処理できる collective2 内のサーバーが、ルール式に一致する要求のために選択されます。

–order 300 のルーティング・ルールは、保守モードのサーバーにテスト要求をルーティングする例を示しています。test=true が照会パラメーターとして追加されている場合、それらの要求は collective1 内の server1 に、そのサーバーが保守モードであっても送信されます。

–order 400 のルーティング・ルールは、リダイレクト・ルールの例を示しています。–order 500 のルーティング・ルールは、拒否ルールの例を示しています。


トピックのタイプを示すアイコン タスク・トピック

ファイル名: twlp_wve_routing_rules.html