API Gateway REST API で VPC リンク統合を使用する際の 500 エラーのトラブルシューティング方法を教えてください。

概要

API Gateway と VPC リンク統合では、トラフィックをバックエンドリソースに転送するのに失敗する場合があります。

また、次のいずれかの理由で "HTTP 500" ステータスコードが返されることもあります。

• VPC リンクは失敗状態である。または、エンドポイントサービスが存在しないか、拒否状態になっている。
• ターゲットグループには、登録されたターゲットが異常または使用されていないと表示される。
• セキュリティグループが特定のポートでのトラフィックを許可していない。
• ネットワークアクセスコントロールリスト (ネットワーク ACL) がトラフィックをブロックしている。
• ターゲットがターゲットポートでリッスンしていない。
• ドメイン名証明書が TLS で有効化された Network Load Balancer または Application Load Balancer と一致していない。

Amazon CloudWatch Logs を API で有効にした場合、エラーの原因を示すエラーメッセージが実行ログに表示されます。

解決策

バックエンド接続を検証

API Gateway のトラブルシューティングを行う前に、以下のいずれかのアクションを実行してください。

• curl や Postman などのツールを使用して、VPC 内から Network Load Balancer の DNS 名にリクエストを送信します。リクエストが失敗した場合は、Network Load Balancer の設定、バックエンドターゲットの状態、またはネットワークに問題があります。
• VPC Reachability Analyzer を使用して、API Gateway VPC リンクサブネットからバックエンドリソースへのトラフィックフローを検証します。

エラーの原因を確認する

CloudWatch API のログ記録を有効にします。また、実行ログを設定します。

注: ログ設定を構成するときは、ログレベルをエラーログと情報ログに設定し、[データトレース] を選択します。これらの設定により、すべてのリクエストログとレスポンスログが提供されます。

エラーの原因を特定するには、CloudWatch の REST API 実行ログを確認してください。次いで、表示されたエラーメッセージに応じて、問題をトラブルシューティングしてください。

"There was an internal error while executing your request" (リクエストの実行中に内部エラーが発生しました) のトラブルシューティング

次のエラーメッセージが表示されます。

"Error: Execution failed due to configuration error: There was an internal error while executing your request"

この問題を解決するには、次の設定を確認します。

• VPC リンクロードバランサーが存在し、削除されていない。
• VPC リンクが利用可能の状態である。VPC リンクが失敗状態の場合は、新しい VPC リンクを作成して API に関連付ける必要があります。
  注: 統合リクエストを変更した後に API をデプロイします。
• ターゲットの Network Load Balancer に関連付けられている VPC リンクエンドポイント接続は利用可能の状態である。
• AWS リージョン固有の API Gateway アカウント ID を [許可プリンシパル] にリストした。
• エンドポイントサービスのエンドポイント接続における API Gateway アカウントからのエンドポイント接続が利用可能の状態である。
• API Gateway が VPC ID をステージ変数で参照している場合、VPC リンク ID が正しいことを確認する。
• VPC リンクロードバランサーは、リクエストを設定した HTTP/HTTPS ポートでリッスンする。リスナーが正しいポートに設定されていることと、ネットワーク ACL がリクエストをブロックしていないことを確認してください。
• ターゲットグループがリクエストを受け入れている。ネットワーク ACL はインバウンドトラフィックとアウトバウンドトラフィックを許可する必要があります。また、セキュリティグループは設定されたポートのインバウンドトラフィックを許可する必要があります。
• リクエストが "HTTP 500" ステータスコードエラーを返す場合、接続は TCP リセット (RST) パケットの合計数を受信する可能性があります。バックエンドサーバーが稼働している必要があります。また、サービスはターゲットポートのバックエンドターゲットで実行されている必要があります。バックエンドターゲットがターゲットポートでリッスンしていることを確認します。
• AWS PrivateLink トラフィックのインバウンドルールを無効化した。[PrivateLink トラフィックにインバウンドルールを適用する] をオンにした場合は、すべてのインバウンドとアウトバウンドのセキュリティグループルールが VPC リンクからのトラフィックに適用されます。VPC リンクからのトラフィックを許可するようにセキュリティグループを設定しない場合でも、セキュリティグループは API Gateway トラフィックをブロックする可能性があります。

"Host name 'domain.com.com' does not match the certificate subject provided by the peer" (ホスト名 'domain.com.com' がピアから提供された証明書のサブジェクトと一致しない) のトラブルシューティング

次のエラーメッセージが表示されます。

"Error: Execution failed due to configuration error: Host name 'domain.com.com' does not match the certificate subject provided by the peer (CN=myinstance.com)"

エンドポイントのドメイン名が、TLS で有効化されたロードバランサーターゲットが返す証明書と一致することを確認してください。サポートされている認証機関プロバイダーリストは、ターゲットインスタンスで設定した証明書を信頼する必要があります。

"PKIX path building failed:...unable to find valid certification path to requested target" (PKIX パス構築失敗:... 要求されたターゲットへの有効な証明書パスが見つかりません) のトラブルシューティング)

次のエラーメッセージが表示されます。

"Error: Execution failed due to configuration error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target"

このエラーは、REST API サービスが、統合から返された証明書に無効のフラグを付けた場合に発生します。統合の TlsConfig プロパティで InSecureSkipVerification を true に設定した場合でも、API Gateway は証明書の基本的な検証を実行します。

API ゲートウェイは以下の情報を確認します。

• 証明書の有効期限
• ホスト名
• ルート認証局 (CA) の存在
  注: API Gateway のトラストチェーンを検証して安全な接続を確立するには、統合に証明書チェーン全体を含めて返す必要があります。チェーン全体には、サーバー証明書からルート CA 証明書までのすべての中間証明書が含まれます。また、ルート CA には keyCertSign を含む keyUsage と CA:TRUE を含む basicConstraintsを含める必要があります。詳細については、「x-amazon-apigateway-integration.tlsConfig オブジェクト」を参照してください。

"Cannot verify ECDH ServerKeyExchange signature" (ECDH ServerKeyExchange の署名を確認できません) のトラブルシューティング

次のエラーメッセージが表示されます。

"Error: Execution failed due to configuration error: Cannot verify ECDH ServerKeyExchange signature"

このエラーは、キーおよび対応する証明書が一致せず、TLS ハンドシェイクが失敗した場合に発生します。この問題を解決するには、設定した CA、証明書、キーに使用したファイルの内容を確認します。

"Execution failed due to an internal error" (内部エラーにより実行に失敗しました) のトラブルシューティング

次のエラーメッセージが表示されます。

"Error: Execution failed due to an internal error"

このエラーは、ターゲットがロードバランサー上でリセットされたため、API Gateway が VPC リンクを介してロードバランサーに接続できなかった場合に発生します。この問題を解決するには、ロードバランサーのデフォルトのタイムアウト (350 秒) よりも長いタイムアウトをターゲットのタイムアウトに設定します。

"Execution failed due to a VPC link error" (VPC リンクエラーにより実行が失敗しました) のトラブルシューティング

次のエラーメッセージが表示されます。

"Error: Execution failed due to a VPC link error"

API Gateway には多くの依存関係があります。依存関係の 1 つに一時的な接続障害があると、エラーが表示されることがあります。エラーの頻度が低い場合は、エクスポネンシャルバックオフを使用して再試行を実装するのがベストプラクティスです。エラーの頻度が高い場合は、AWS サポートに連絡してください。エラーを示す API Gateway 実行ログを必ず提供してください。

"Execution failed due to configuration error: Not a valid protocol version" (構成エラーにより実行に失敗しました: 有効なプロトコルバージョンではありません) のトラブルシューティング

次のエラーメッセージが表示されます。

"Error: Execution failed due to configuration error: Not a valid protocol version"

このエラーは、統合が、HTTP 仕様に準拠していない無効な HTTP 応答で応答した場合に発生します。統合バックエンドは、有効でないデータを API Gateway に送り返す可能性があります。

この問題をトラブルシューティングするには、次の手順を実行します。

• API Gateway から行ったリクエストを再現します。API Gateway が使用するサービスエンドポイントをテストするには、サービスエンドポイント ID にリンクされた VPC エンドポイントを作成します。パケットキャプチャを実行して、統合バックエンドから返された応答を確認することもできます。
• 重複暗号化を避けるために、ターゲットの応答に応じて、ロードバランサーのプロトコルを TLS または TCP に変更します。
• 統合の TlsConfig プロパティで insecureSkipVerification が true に設定されていることを確認してください。

エラーと問題の監視と検出

次のツールを使用して、問題が一時的なものなのか、それとも永続的な構成上の問題なのかを判断してください。

• CloudWatch の 5xxError および Integration Latency API Gateway メトリクスをモニタリングしてパターンを検出します。
• AWS X-Ray トレースを有効にして、API Gateway から VPC リンクへのリクエストパス、VPC リンクからネットワークロードバランサーへのリクエストパス、およびネットワークロードバランサーからバックエンドへのリクエストパスを監視します。

関連情報

Amazon API Gateway プライベート統合の VPC リンクについて

Amazon CloudWatch のメトリクスを使用して REST API の実行をモニタリングする

API Gateway のプライベート統合の Network Load Balancer を設定する