4.2. 3scale 標準ポリシーからのポリシーチェーン

API プロダクトごとにポリシーチェーンを指定することができます。ポリシーチェーンは以下を行います。

  • APIcast がリクエストに適用するポリシーを指定する。
  • ポリシーの設定情報を提供する。
  • APIcast がポリシーを適用する順番を決定する。

チェーン内でポリシーを正しい順番で設定するには、APIcast がポリシーを API 利用者のリクエストに適用する方法を理解することが重要です。

4.2.1. APIcast NGINX フェーズが 3scale ポリシーを処理する仕組み

3scale API ゲートウェイ (APIcast) は、NGINX プロキシー Web サーバーを使用してポリシーを適用します。APIcast が API 利用者からリクエストを受け取ると、APIcast は要求を一連の NGINX フェーズの順番どおりに処理します。それぞれの NGINX フェーズでは、APIcast は以下のポリシーを適用して元のリクエストを変更することができます。

  • アップストリーム API ポリシーチェーンのポリシー。ポリシーチェーンは、順番が設定されたポリシーのリストです。デフォルトでは、アップストリーム API のポリシーチェーンには 3scale APIcast ポリシーが含まれます。API プロバイダーは、3scale プロダクトのポリシーチェーンにポリシーを追加することができます。APIcast は、アップストリーム API ポリシーチェーンのポリシーを、そのアップストリーム API に送信された API 利用者のリクエストだけに適用します。
  • グローバル 3scale ポリシーチェーンのポリシー。API プロバイダーは、3scale の環境変数を設定して、グローバルポリシーチェーンを更新することができます。APIcast は、グローバルポリシーチェーンのポリシーをすべての API 利用者のリクエストに適用します。

同じポリシーがアップストリーム API のポリシーチェーンおよびグローバルポリシーチェーンにある場合は、アップストリーム API のポリシーチェーンのポリシー設定が優先されます。

APIcast がすべての NGINX フェーズの必要な処理を行った後に、APIcast はリクエストの結果をアップストリーム API に送信します。そのため、処理によって API 利用者のリクエストを変更できるため、希望の動作を実現するには、NGINX フェーズがポリシーを処理する順序を理解することが重要です。

NGINX フェーズの順序と説明

APIcast が API 利用者からリクエストを受け取ると、APIcast はアップストリーム API のポリシーチェーンおよびグローバルポリシーチェーンのポリシーを適用してリクエストを処理します。各 3scale ポリシーは 1 つ以上の関数を定義します。APIcast は、一連の NGINX フェーズの順番どおりにポリシーの関数を実行します。各フェーズでは、NGINX は適用されるポリシーで定義され、そのフェーズでの実行を指定する関数を実行します。以下の表は、ポリシー関数を実行する NGINX のフェーズのリストを示しています。この表に記載されていない追加の NGINX フェーズは、ポリシーチェーン内のポリシーの順序によって影響を受けない処理を実行します。

NGINX フェーズのリストこのフェーズでの処理の説明

rewrite

要求のターゲット URI を変更する関数を実行します。

access

リクエストを行うためのクライアントの承認を検証する関数を実行します。

content

アップストリーム API に送信されるリクエストのコンテンツを生成します。

NGINX は、content フェーズ内の 1 つのポリシーのみを適用します。ポリシーチェーン内の複数のポリシーがリクエストのコンテンツで動作する場合、NGINX はチェーン内で最も早いポリシーのみを適用します。組み込みの 3scale APIcast ポリシーは常にポリシーチェーンにあり、content フェーズで NGINX の処理が必要になるため、これを理解することが重要です。

たとえば、3scale APIcast ポリシーと Upstream ポリシーの両方が、リクエストを更新してアップストリーム API のパスを指定します。NGINX は、これらの関数を content フェーズで処理します。3scale APIcast ポリシーが Upstream ポリシーの前にある場合、NGINX はアップストリーム API の設定を使用して、そのパスを修正したリクエストに追加します。Upstream ポリシーが 3scale APIcast ポリシーの前にある場合には、NGINX は Upstream ポリシーの式を評価します。一致がある場合、NGINX は修正したリクエストで適宜アップストリーム API のパスを変更します。

balancer

負荷分散関数を実行します。

header_filter

リクエストヘッダーを処理する関数を実行します。

body_filter

リクエストボディーを処理する関数を実行します。

post_action

NGINX がヘッダーとボディーで関数を実行した後にリクエストを処理する関数を実行します。

log

リクエストに関するログ情報を生成します。

metrics

Prometheus エンドポイントから受信されるデータで機能します。

ポリシーの順序によって影響を受けない処理を実行する NGINX フェーズの例:

  • APIcast が起動すると、NGINX は init フェーズに関連付けられたタスクを実行します。
  • APIcast ワーカーが起動すると、NGINX は init_worker フェーズに関連付けられたタスクを実行します。
  • APIcast が HTTPS 接続を終了すると、NGINX は ssl_certificate フェーズに関連付けられたタスクを実行します。

NGINX がポリシー関数を実行する順序

API プロバイダーは、1 つ以上のポリシーを 3scale プロダクトに追加してポリシーチェーンを形成できます。各フェーズでは、NGINX はそのフェーズでの実行を指定するポリシー関数のみを処理します。各ポリシー関数は、1 つの NGINX フェーズでの処理中に APIcast がそのデフォルトの動作をどのように変更するかを指定します。たとえば、header_filter フェーズでは、NGINX は header_filter を指定し、リクエストヘッダーで操作する関数を処理します。各フェーズでは、NGINX は、ポリシーチェーンにある順序で該当する関数を処理します。

ポリシーは、context オブジェクトを使用してデータを共有できます。ポリシーは、各フェーズで context オブジェクトを読み取ったり、変更したりできます。

NGINX がポリシー関数を実行する順序は、以下の要素によって異なります。

  • ポリシーチェーンでのポリシーの位置
  • 特定のポリシー関数を処理する NGINX フェーズ

必要な動作を得るには、ポリシーチェーンの順序を正しく指定する必要があります。ポリシー適用の結果は、ポリシーチェーン内の位置により異なる可能性があるためです。以下の図は、NGINX がポリシーを適用する順序の例を示しています。

APIcast NGINX 実行フェーズおよび 3scale ポリシーチェーン

上の図では、ポリシー A がポリシーチェーンの最初のものです。しかし、NGINX は、まずポリシー B の関数を処理します。その関数が NGINX の最初のフェーズである rewrite フェーズに関連するためです。

ここで、以下の関数を持つポリシー A およびポリシー B が含まれるプロダクトのポリシーチェーンについて検討します。

  • ポリシー A は以下を指定します。

    • access フェーズで実行する NGINX の関数 A1
    • header_filter フェーズで実行する NGINX の関数 A2
  • ポリシー B は以下を指定します。

    • rewrite フェーズで実行する NGINX の関数 B1
    • header_filter フェーズで実行する NGINX の関数 B2

以下の図は、NGINX がプロダクトのポリシー関数を実行する順序を示しています。

APIcast NGINX 実行フェーズおよびサンプル 3scale ポリシーチェーン

APIcast がこのプロダクトにより公開されるアップストリーム API へのアクセスリクエストを受け取ると、APIcast はプロダクトのポリシーチェーンを確認し、以下の表で説明するように関数を実行します。

NGINX フェーズのリストNGINX が各フェーズで実行する機能

rewrite

ポリシー Brewrite フェーズに指定する関数 B1 を実行します。

access

ポリシー Aaccess フェーズに指定する関数 A1 を実行します。

content

ポリシー A とポリシー B のいずれも、content フェーズで実行する関数を指定しません。

balancer

ポリシー A とポリシー B のいずれも、balancer フェーズで実行する関数を指定しません。

header_filter

ポリシーチェーンはポリシー A を指定し、次にポリシー B を指定します。したがって、このフェーズは、ポリシー Aheader_filter フェーズに指定する関数 A2 を実行し、続いてポリシー Bheader_filter フェーズに指定する関数 B2 を実行します。

body_filter

ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。

post_action

ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。

log

ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。

この例では、ポリシー A がポリシーチェーンの最初のものですが、ポリシー B の関数が NGINX が実行する最初の関数です。これは、ポリシー B が NGINX が (他のフェーズよりも前にある) rewrite フェーズで処理する関数 B1 を指定するためです。

別の例として、以下のポリシーチェーンについて考えてみましょう。

  1. URL Rewriting
  2. 3scale APIcast (すべてのプロダクトに割り当てられたデフォルトポリシー)

URL Rewriting ポリシーは、リクエストのターゲットパスを変更します。APIcast は rewrite フェーズで URL Rewriting 関数を実行します。3scale APIcast ポリシーは、APIcast が rewrite フェーズで実行する関数に加えて、APIcast が他の 3 つのフェーズで実行する関数を定義します。URL Rewriting ポリシーが最初になると、3scale APIcast ポリシーにより、書き換えられたパスにマッピングルールが適用されます。3scale APIcast ポリシーが最初にあり、URL Rewriting ポリシーが 2 番目の場合には、3scale APIcast ポリシーにより、元のパスにマッピングルールが適用されます。