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

制限事項

• サーキットブレーカのプラグインは、専用インスタンスのAPIに対してのみ有効です。

• 各条件式には、最大512文字を使用できます。

• 各プラグインには、最大50 KBのメタデータを含めることができます。

1. 概要

API Gatewayは、バックエンドパフォーマンスが異常な場合にAPIを保護するために、各APIにサーキットブレーカーを提供します。 デフォルトでは、APIのバックエンドで30秒以内にタイムアウトが1,000回発生すると、回路ブレーカーがトリップします。 遮断器は90秒間開いたままであり、その間にすべてのAPI要求に対して次のエラーが返されます: ステータス=503、X-Ca-error-Code=D503CB。 90秒後、回路ブレーカは限られた数の同時API要求を通過させる。 これらの要求が成功すると、回路ブレーカが閉じ、API要求を再び期待通りに処理できます。

サーキットブレーカタイプのプラグインをAPIにバインドして、そのサーキットブレーカの設定をカスタマイズすることもできます。 サーキットブレーカのプラグインは、専用インスタンスのAPIに対してのみ有効です。 遮断器の次の構成をカスタマイズできます。

• 回路ブレーカーがトリップする条件。 バックエンドでのタイムアウトの発生回数、または指定されたエラーの発生回数が指定された期間内にしきい値に達した後に、回路ブレーカーがトリップするように指定できます。

• タイムアウトの発生回数、長い応答時間の発生回数、または指定されたエラーの発生回数をバックエンドでチェックする時間ウィンドウは、トリップするかどうかを決定するために回路遮断器によってチェックされる。

• 遮断器がトリップした後に開いたままである期間。

• サーキットブレーカが開いているときにAPIリクエストが送信されるバックエンド。

2. 設定

回路ブレーカープラグインは、専用インスタンスのAPIに対してのみ有効です。 サーキットブレーカーのプラグインを共有インスタンスのAPIにバインドする場合、サーキットブレーカーはデフォルトの設定を使用します。

2.1 バックエンドでのタイムアウトの発生回数がしきい値に達した後に回路ブレーカーがトリップすることを指定します

回路ブレーカープラグインを設定するときに、バックエンドでのタイムアウトの発生回数が指定された期間内にしきい値に達した後に回路ブレーカーがトリップするように指定できます。 APIに指定されたバックエンドタイムアウトしきい値が10秒で、10秒以内にバックエンドから応答が受信されない場合、1回のタイムアウトがカウントされます。

timeoutThreshold: 15         # The threshold of the number of occurrences of timeout at the backend.
windowInSeconds: 30          # The time window during which the number of occurrences of timeout at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15       # The period of time during which the circuit breaker stays open after it trips.
downgradeBackend:            # The backend to which API requests are directed when the circuit breaker is open.
  type: mock
  statusCode: 418

上記のコードスニペットでは、次のパラメーターを指定できます。

• timeoutThreshold: バックエンドでのタイムアウトの発生回数のしきい値。 このしきい値に達すると、回路ブレーカがトリップします。 このパラメータの最大値は5000です。 適切な値を指定することを推奨します。 値が小さい場合、タイムアウトが数回だけ発生した後、回路ブレーカは定期的にトリップします。

• windowInSeconds: バックエンドでのタイムアウトの発生回数が回路ブレーカによってチェックされ、トリップするかどうかが判断される時間ウィンドウ。 有効な値: 10〜90。 単位は秒です。

• openTimeoutSeconds: トリップ後にサーキットブレーカが開いたままになる期間。 有効な値: 15 ~ 300 単位は秒です。

• downgradeBackend: オプションです。 サーキットブレーカが開いているときにAPIリクエストが送信されるバックエンド。

2.2 バックエンドでのロングレスポンスの発生回数がしきい値に達した後に回路ブレーカーがトリップすることを指定します

回路ブレーカープラグインを設定するときに、バックエンドでの長い応答の発生回数が指定された期間内にしきい値に達した後に回路ブレーカーがトリップするように指定できます。 バックエンドの応答時間は、API Gatewayがバックエンドにリクエストを送信してから、API Gatewayがバックエンドから応答を受信するまでの時間です。

errorThreshold: 10         # The threshold of the number of occurrences of long response at the backend.
windowInSeconds: 60          # The time window during which the number of occurrences of long response at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 120        # The period of time during which the circuit breaker stays open after it trips.
errorCondition: "$LatencyMilliSeconds > 500"     # The conditional expression that is used to determine whether the backend response is counted as a long response. In this example, if the backend response time exceeds 500 ms, the response is considered as a long response.
downgradeBackend:               # The backend to which API requests are directed when the circuit breaker is open.
  type: mock
  statusCode: 403

上記のコードスニペットでは、次のパラメーターを指定できます。

• errorThreshold: 長い応答の発生回数のしきい値。

• windowInSeconds: バックエンドでのタイムアウトの発生回数が回路ブレーカによってチェックされ、トリップするかどうかが判断される時間ウィンドウ。 有効な値: 10〜90。 単位は秒です。

• openTimeoutSeconds: トリップ後にサーキットブレーカが開いたままになる期間。 有効な値: 15 ~ 300 単位は秒です。

• errorCondition: バックエンド応答が長い応答としてカウントされるかどうかを判断するために使用される条件式。 $LatencyMilliSecondsおよび $LatencySeconds変数を使用できます。 $LatencyMilliSecondsの単位はミリ秒です。 $LatencySecondsの単位は秒です。

• downgradeBackend: オプションです。 サーキットブレーカが開いているときにAPIリクエストが送信されるバックエンド。

2.3 バックエンドで指定されたエラーの発生回数がしきい値に達した後に回路ブレーカーがトリップすることを指定します

回路遮断器プラグインを設定するとき、バックエンドで指定されたエラーの発生回数が指定された期間内にしきい値に達した後に回路遮断器がトリップするように指定できます。

errorCondition: "$StatusCode == 503"  # The conditional expression that specifies the error whose number of occurrences is checked by the circuit breaker to determine whether to trip.
errorThreshold: 1000                  # The threshold of the number of occurrences of the specified error.
windowInSeconds: 30                   # The time window during which the number of occurrences of the specified error at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15                # The period of time during which the circuit breaker stays open after it trips.
downgradeBackend:                     # The backend to which API requests are directed when the circuit breaker is open.
  type: "HTTP"
  address: "http://api.foo.com"
  path: "/system-busy.json"
  method: GET

• errorCondition: トリップするかどうかを判断するために回路ブレーカによって発生数がチェックされるエラーを指定する条件式。 $StatusCodeおよび $LatencySeconds変数を使用できます。

  • 条件式を $StatusCode = 503または $StatusCode = 504に指定した場合、回路ブレーカはHTTPステータスコードの503または504の合計発生数をチェックします。

  • 条件式を $LatancySeconds > 30に指定した場合、回路ブレーカーは30秒を超えるタイムアウトの発生回数の合計をチェックします。

• errorThreshold: 指定されたエラーの発生回数のしきい値。

• windowInSeconds: バックエンドでのタイムアウトの発生回数が回路ブレーカによってチェックされ、トリップするかどうかが判断される時間ウィンドウ。 有効な値: 10〜90。 単位は秒です。

• openTimeoutSeconds: トリップ後にサーキットブレーカが開いたままになる期間。 有効な値: 15 ~ 300 単位は秒です。

• downgradeBackend: オプションです。 サーキットブレーカが開いているときにAPIリクエストが送信されるバックエンド。

2.4 正確なステータス制御

API Gatewayサービスは、高い可用性とパフォーマンスを確保するために、クラスター内の複数のノードにデプロイされます。 デフォルトでは、異なるサービスノードが独自に回路ブレーカのステータスを計算して保存します。 結果として、全体的な観点から、回路遮断器は、ステータスの不正確さを有し得る。 正確なサーキットブレーカのステータスが必要な場合は、useGlobalStateフィールドをプラグイン構成に追加できます。 例：

---
timeoutThreshold: 15 # The threshold of the number of occurrences of timeout at the backend.
windowInSeconds: 30 # The time window during which the number of occurrences of timeout at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15 # The period of time during which the circuit breaker stays open after it trips.
useGlobalState: true # Accurate status control is enabled.
downgradeBackend: # The backend to which API requests are directed when the circuit breaker is open.
 type: mock
 statusCode: 302
 body: |
 <result>
 <errorCode>I's a teapot</errorCode>
 </result>

useGlobalStateのデフォルト値はfalseです。 trueに設定すると、現在のインスタンスの約束された1秒あたりのクエリ (QPS) とサービスレベル契約 (SLA) のメトリックを損なわない程度のサービスパフォーマンス損失を犠牲にして、正確なサーキットブレーカのステータスが取得されます。

2.5 指定された期間内にすべてのリクエストに対して特定のエラーが発生したリクエストの割合がしきい値に達した後に回路ブレーカーがトリップするように指定します。

API Gatewayは、次のいずれかの条件が満たされると、回路ブレーカーをトリップします。

• errorThreshold: バックエンドでの特定のエラーの発生回数のしきい値。 このフィールドは、条件式と組み合わせて使用されます。

• timeoutThreshold: バックエンドでのタイムアウトの発生回数のしきい値。

• errorThresholdByPercent: タイムウィンドウ内のリクエストの総数に対する特定のエラーが発生したリクエストの数の割合のしきい値。

• timeoutThresholdByPercent: タイムウィンドウ内のリクエストの総数に対するタイムアウトが発生したリクエスト数の割合のしきい値。

次のコードは例を示しています。

---
windowInSeconds: 3  # The time window during which the circuit breaker determines whether to trip. Valid values: 10 to 90. Unit: seconds.
openTimeoutSeconds: 3
errorThreshold: 90  # The threshold of the number of occurrences of the specified error.
timeoutThreshold: 90   # The threshold of the number of occurrences of timeout.
errorThresholdByPercent: 20    # The threshold of the percentage of requests in which the specified error occurs to the total number of requests.
timeoutThresholdByPercent: 20   # The threshold of the percentage of requests in which timeout occurs to the total number of requests.
errorCondition: "$StatusCode = 500"   # The error condition.
downgradeBackend:
  type: mock
  statusCode: 418
  body: |
    <result>
      <errorCode>I's a teapot</errorCode>
    </result>

2.6 回路ブレーカがトリップしたときの要求のスロットル

サーキットブレーカがトリップすると、APIに一時的なスロットリング設定が追加され、サーキットブレーカが開いているときまたは半分開いているときに、この設定に基づいてすべてのトラフィックがスロットリングされます。 例：

---
windowInSeconds: 1             # The time window in which the circuit breaker checks the number of occurrences of timeout at the backend.
openTimeoutSeconds: 15          # The period of time during which the circuit breaker stays open after it trips.
errorThreshold: 3
errorCondition: "$LatencyMilliSeconds > 1"
downgradeTrafficLimit:               # The backend to which API requests are directed when the circuit breaker is open.
  limit: 2
  period: MINUTE

3. サーキットブレーカが開いているときにAPIリクエストが送信されるバックエンドを設定する

downgradeBackendパラメーターを設定して、回路ブレーカーが開いているときにAPIリクエストが送信されるバックエンドを指定できます。 バックエンドの設定は、API GatewayにインポートされるAPI仕様ファイルと一致している必要があります。 詳細については、「SwaggerファイルをインポートしてAPI Gateway拡張機能を持つAPIを作成する」をご参照ください。 サンプルを使用して、次のタイプのバックエンドを設定できます。

• HTTP

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

• HTTP-VPC

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

• Function Compute

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

• モック

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

4. エラーコード