API Gateway:サーキットブレーカープラグイン (専有インスタンスのみ)

制限事項

• 専有インスタンスのみ。

• 式あたり最大 512 文字。

• プラグイン設定の最大サイズ：50 KB。

1. 概要

デフォルトでは、API バックエンドで 30 秒以内に 1,000 回のタイムアウトが発生すると、サーキットブレーカーがトリップして 90 秒間オープン状態になります。この期間中、すべてのリクエストはエラーコード X-Ca-Error-Code=D503CB とともに Status=503 を返します。90 秒後、サーキットブレーカーはハーフオープン状態になり、少数のリクエストを通過させます。バックエンドが回復すると、サーキットブレーカーはクローズし、リクエストが正常に再開します。

専有インスタンス では、サーキットブレーカープラグイン を使用して、以下の サーキットブレーカー 設定をカスタマイズできます。

• トリップ条件：タイムウィンドウ内でバックエンドのタイムアウトまたは指定されたエラーがしきい値を超えると、サーキットブレーカーがトリップします。

• トリップ条件を評価するためのタイムウィンドウ。

• サーキットブレーカーがトリップした後のオープン期間。

• サーキットブレーカーがオープン状態の間のリクエスト用のフォールバックバックエンド。

2. 設定

サーキットブレーカープラグインの設定は、専有インスタンス上の API にのみ適用されます。サーバーレスインスタンスでは、プラグインが API にバインドされていても、デフォルトのサーキットブレーカー設定が使用されます。

2.1 バックエンドタイムアウトに基づく縮退ポリシーの設定

バックエンドタイムアウトに基づいて縮退ポリシーを設定します。バックエンドが API で定義されたタイムアウト期間内に応答しない場合、リクエストはタイムアウトとしてカウントされます。

timeoutThreshold: 15         # バックエンドでのタイムアウト発生回数のしきい値。
windowInSeconds: 30          # バックエンドでのタイムアウト発生回数をサーキットブレーカーがチェックしてトリップを判断するためのタイムウィンドウ。
openTimeoutSeconds: 15       # トリップ後にサーキットブレーカーがオープン状態を維持する期間。
downgradeBackend:            # サーキットブレーカーがオープン状態のときに API リクエストが転送されるバックエンド。
  type: mock
  statusCode: 418

フィールド：

• timeoutThreshold：サーキットブレーカーがトリップするバックエンドタイムアウトの回数。最大値：5000。値が小さすぎると、頻繁にトリップが発生します。

• windowInSeconds：評価タイムウィンドウ。有効値：10～90。単位：秒。

• openTimeoutSeconds：サーキットブレーカーがオープン状態を維持する期間。有効値：15～300。単位：秒。

• downgradeBackend：(任意) サーキットブレーカーがオープン状態のときに使用されるフォールバックバックエンド。

2.2 バックエンドの応答時間に基づく縮退ポリシーの設定

ゲートウェイがリクエストを送信してから応答を受信するまでの時間で測定される、バックエンドの応答時間に基づいて縮退ポリシーを設定します。

errorThreshold: 10         # バックエンドでの長い応答の発生回数のしきい値。
windowInSeconds: 60          # バックエンドでの長い応答の発生回数をサーキットブレーカーがチェックしてトリップを判断するためのタイムウィンドウ。
openTimeoutSeconds: 120        # トリップ後にサーキットブレーカーがオープン状態を維持する期間。
errorCondition: "$LatencyMilliSeconds > 500"     # バックエンドの応答が長い応答としてカウントされるかを判断する条件式。この例では、バックエンドの応答時間が 500 ms を超えると、その応答は長い応答と見なされます。
downgradeBackend:               # サーキットブレーカーがオープン状態のときに API リクエストが転送されるバックエンド。
  type: mock
  statusCode: 403

フィールド：

• errorThreshold：サーキットブレーカーがトリップする遅い応答の回数。

• windowInSeconds：評価タイムウィンドウ。有効値：10～90。単位：秒。

• openTimeoutSeconds：サーキットブレーカーがオープン状態を維持する期間。有効値：15～300。単位：秒。

• errorCondition：遅い応答を定義する式。使用可能な変数：$LatencyMilliSeconds (ミリ秒) および $LatencySeconds (秒)。

• downgradeBackend：(任意) サーキットブレーカーがオープン状態のときに使用されるフォールバックバックエンド。

2.3 バックエンドエラーに基づく縮退ポリシーの設定

バックエンドのエラーコードに基づいて縮退ポリシーを設定します。

errorCondition: "$StatusCode == 503"  # 発生回数をサーキットブレーカーがチェックし、トリップするかどうかを判断するエラーを指定する条件式。
errorThreshold: 1000                  # 指定されたエラーの発生回数のしきい値。
windowInSeconds: 30                   # バックエンドでの指定されたエラーの発生回数をサーキットブレーカーがチェックしてトリップを判断するためのタイムウィンドウ。
openTimeoutSeconds: 15                # トリップ後にサーキットブレーカーがオープン状態を維持する期間。
downgradeBackend:                     # サーキットブレーカーがオープン状態のときに API リクエストが転送されるバックエンド。
  type: "HTTP"
  address: "http://api.foo.com"
  path: "/system-busy.json"
  method: GET

• errorCondition：エラー式。使用可能な変数：$StatusCode (ステータスコード) および $LatencySeconds (レイテンシー、秒単位)。

  • たとえば、式 $StatusCode = 503 or $StatusCode = 504 は、バックエンド応答のステータスコードが 503 または 504 の場合に true と評価されます。

  • たとえば、$LatencySeconds > 30 は、タイムアウトが 30 秒を超えたことを示します。

• errorThreshold：サーキットブレーカーがトリップする、一致するエラーの回数。

• windowInSeconds：評価タイムウィンドウ。有効値：10～90。単位：秒。

• openTimeoutSeconds：サーキットブレーカーがオープン状態を維持する期間。有効値：15～300。単位：秒。

• downgradeBackend：(任意) サーキットブレーカーがオープン状態のときに使用されるフォールバックバックエンド。

2.4 正確なステータス制御

API Gateway は複数のクラスターノードで実行され、各ノードは独自のサーキットブレーカー状態を維持します。これにより、ノード間でステータスの不一致が生じる可能性があります。グローバルに一貫したサーキットブレーカーのステータスを有効にするには、プラグイン設定に useGlobalState フィールドを追加します。

---
timeoutThreshold: 15 # バックエンドでのタイムアウト発生回数のしきい値。
windowInSeconds: 30 # バックエンドでのタイムアウト発生回数をサーキットブレーカーがチェックし、トリップするかどうかを判断するためのタイムウィンドウ。
openTimeoutSeconds: 15 # トリップ後にサーキットブレーカーがオープン状態を維持する期間。
useGlobalState: true # 正確なステータス制御が有効になります。
downgradeBackend: # サーキットブレーカーがオープン状態のときに API リクエストが転送されるバックエンド。
 type: mock
 statusCode: 302
 body: |
   <result>
     <errorCode>It's a teapot</errorCode>
   </result>

useGlobalState のデフォルト値は false です。これを true に設定すると、わずかなパフォーマンスオーバーヘッドと引き換えに正確なステータスが有効になりますが、インスタンスの保証 QPS および SLA には影響しません。

2.5 パーセンテージによる縮退ポリシーの設定

以下の 4 つの条件のいずれかが満たされると、サーキットブレーカーがトリップします。すべての条件は同じ優先度です。

• errorThreshold：サーキットブレーカーがトリップするバックエンドエラー (errorCondition に一致) の回数。

• timeoutThreshold：サーキットブレーカーがトリップするバックエンドタイムアウトの回数。

• errorThresholdByPercent：エラーレートのしきい値。前のタイムウィンドウのエラーレートに対して評価されます。

• timeoutThresholdByPercent：タイムウィンドウ内の総リクエスト数に対するタイムアウトレートのしきい値 (パーセンテージ)。

例：

---
windowInSeconds: 10  # サーキットブレーカーがトリップするかどうかを判断するタイムウィンドウ。有効値： 10～90。単位： 秒。
openTimeoutSeconds: 15 # トリップ後にサーキットブレーカーがオープン状態を維持する期間。有効値： 15～300。単位： 秒。
errorThreshold: 90  # 指定されたエラーの発生回数のしきい値。
timeoutThreshold: 90   # タイムアウトの発生回数のしきい値。
errorThresholdByPercent: 20    # 総リクエスト数に対する、指定されたエラーが発生したリクエストの割合のしきい値。
timeoutThresholdByPercent: 20   # 総リクエスト数に対する、タイムアウトが発生したリクエストの割合のしきい値。
errorCondition: "$StatusCode = 500"   # エラー条件。
downgradeBackend:
  type: mock
  statusCode: 418
  body: |
    <result>
      <errorCode>It's a teapot</errorCode>
    </result>

2.6 サーキットブレーカートリップ時のリクエストのスロットリング

サーキットブレーカーがトリップすると、サーキットブレーカーがオープンまたはハーフオープン状態の間、すべてのトラフィックに一時的なスロットリング設定が適用されます。

---
windowInSeconds: 10             # サーキットブレーカーがバックエンドでのタイムアウト発生回数をチェックするタイムウィンドウ。
openTimeoutSeconds: 15          # トリップ後にサーキットブレーカーがオープン状態を維持する期間。
errorThreshold: 3
errorCondition: "$LatencyMilliSeconds > 1"
downgradeTrafficLimit:               # サーキットブレーカーがオープン状態のときに適用されるトラフィック制限。
  limit: 2
  period: MINUTE

3. フォールバックバックエンドの設定

downgradeBackend を使用して、サーキットブレーカーがオープン状態のときにフォールバックバックエンドを指定します。バックエンドの設定は、API Gateway で使用される API 仕様フォーマット (「API Gateway 拡張機能を使用して API を作成するための Swagger ファイルのインポート」) と一致している必要があります。以下のバックエンドタイプがサポートされています。

• HTTP バックエンド

---
downgradeBackend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  path: "/users/{userId}"
  method: GET
  timeout: 7000

• HTTP バックエンド (VPC)

---
downgradeBackend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  path: "/users/{userId}"
  method: GET
  timeout: 10000

• Function Compute

---
downgradeBackend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"

• MOCK

---
downgradeBackend:
  type: MOCK
  mockResult: "mock result sample"
  mockStatusCode: 200
  mockHeaders:
    - name: Content-Type
      value: text-plain
    - name: Content-Language
      value: zhCN

4. エラーコード