API Gateway용 VPC 링크 통합 시 발생하는 500 오류를 해결하려면 어떻게 해야 하나요?

간략한 설명

VPC 링크가 있는 AWS API Gateway는 다음과 같은 이유로 트래픽을 백엔드 리소스로 전달하지 못하고 HTTP 500 상태 코드를 반환할 수 있습니다.

• VPC 링크가 실패 상태입니다. 또는 엔드포인트 서비스가 삭제되었거나 거부 상태입니다.
• 대상 그룹에 등록된 대상이 비정상 상태이거나 사용 중이 아닙니다.
  **참고:**60일 동안 VPC 링크를 통해 트래픽이 전송되지 않으면 해당 링크가 비활성 상태가 됩니다. 자세한 내용은 HTTP API용 VPC 링크 작업을 참조하세요.
• 보안 그룹은 특정 포트의 트래픽을 허용하지 않습니다.
• 네트워크 액세스 제어 목록(네트워크 ACL)은 트래픽을 차단합니다.
• 대상이 대상 포트에서 수신 대기하고 있지 않습니다.
• 도메인 이름 인증서가 TLS 활성화 Network Load Balancer 또는 Application Load Balancer와 일치하지 않습니다.

API에 대해 Amazon CloudWatch Logs가 활성화된 경우 실행 로그에 오류의 원인이 포함된 오류 메시지가 나타납니다.

CloudWatch logs의 HTTP 500 오류 메시지 예시

"Thu Aug 04 17:48:21 UTC 2022 : Execution failed due to configuration error: There was an internal error while executing your request Thu Aug 04 17:48:21 UTC 2022 : Method completed with status: 500"

-또는-

"Thu Aug 04 19:50:21 UTC 2022 : Execution failed due to configuration error: Host name 'domain.com.com' does not match the certificate subject provided by the peer (CN=myinstance.com)
Thu Aug 04 19:50:21 UTC 2022 : Method completed with status: 500"

해결 방법

오류 원인 확인

CloudWatch API 로깅을 활성화합니다. 실행 로깅을 구성했는지 확인하세요.

**참고:**로깅 설정을 구성할 때 로그 수준에서 정보를 선택합니다. 그런 다음 전체 요청/응답 데이터 로그를 선택합니다.

오류의 원인을 확인하려면 CloudWatch에서 REST API 실행 로그를 검토하세요.

실행 로그에서 오류 메시지를 확인하세요.

오류: Execution failed due to configuration error: There was an internal error while executing your request

다음 구성을 확인하세요.

• VPC 링크 로드 밸런서가 존재하며, 삭제되지 않았는지 확인하세요.
• VPC 링크가 사용 가능 상태인지 확인합니다. VPC 링크가 실패 상태인 경우 새 VPC 링크를 생성하여 API와 연결해야 합니다.
  **참고:**통합 요청을 수정한 후 API를 배포합니다.
• VPC 링크 엔드포인트 연결이 사용 가능 상태인지 확인합니다.
• VPC ID가 단계 변수와 함께 참조되는 경우 VPC 링크 ID가 올바른지 확인합니다.
• VPC 링크 로드 밸런서가 요청이 구성된 HTTP/HTTPS 포트에서 수신 대기하고 있는지 확인합니다. 리스너가 올바른 포트에 구성되어 있는지 확인합니다. 네트워크 ACL이 요청을 차단하지 않는지 확인합니다.
• 대상 그룹이 요청을 수락하는지 확인합니다. 네트워크 ACL은 인바운드 및 아웃바운드 트래픽을 허용해야 하며, 보안 그룹은 구성된 포트에 대한 인바운드 트래픽을 허용해야 합니다.
• 요청에서 500 오류가 반환되는 경우 연결에서 TCP RST 패킷을 수신할 수 있습니다. 백엔드 서버가 실행 중인지 확인합니다. 대상 포트의 백엔드 대상에서 서비스가 실행되고 있는지 확인합니다. 백엔드 대상이 대상 포트에서 수신 대기하고 있는지 확인합니다.
• AWS PrivateLink 트래픽에 인바운드 규칙 적용 옵션이 꺼져 있는지 확인합니다. PrivateLink 트래픽에 인바운드 규칙을 적용하면 VPC 링크의 트래픽에 모든 인바운드 및 아웃바운드 보안 그룹 규칙이 적용됩니다. VPC 링크의 트래픽을 허용하도록 보안 그룹을 구성하지 않으면 보안 그룹이 API Gateway 트래픽을 차단할 수 있습니다. VPC 링크에서 오지 않는 트래픽에 보안 그룹 규칙을 적용하려면 PrivateLink 트래픽에 대한 인바운드 규칙 적용을 끄세요.

오류: 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 활성화 로드 밸런서 대상이 반환하는 인증서와 일치하는지 확인하세요.

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

이 오류는 API Gateway에서 루트 인증 기관을 찾을 수 없는 경우 발생합니다. 통합 TlsConfig 속성에서 insecureSkipVerification이 true로 설정되어 있어도 API Gateway는 기본 인증서 검증을 수행합니다. 검증은 다음 정보를 검토합니다.

• 인증서 만료 날짜
• 호스트 이름
• 루트 인증 기관의 존재 여부

대상 인스턴스에서 구성한 인증서는 지원되는 인증 기관 공급자 목록에서 신뢰할 수 있어야 합니다.

오류: Execution failed due to configuration error: Cannot verify ECDH ServerKeyExchange signature

이 오류는 키와 해당 인증서가 일치하지 않고 TLS 핸드셰이크가 실패하는 경우 발생합니다. 이 문제를 해결하려면 구성된 인증 기관, 인증서 및 키에 사용한 파일의 내용을 확인하세요.

오류: Execution failed due to an internal error

이 오류는 대상이 로드 밸런서에서 재설정되기 때문에 Amazon API Gateway가 VPC 링크를 통해 로드 밸런서에 연결하지 않은 경우 발생합니다. 이 문제를 해결하려면 대상의 제한 시간을 로드 밸런서의 제한 시간 기본값(350초)보다 길게 설정하세요.

오류: Execution failed due to configuration error: Not a valid protocol version: {Text of string}

이 오류는 통합이 유효하지 않고 HTTP 사양을 준수하지 않는 HTTP 응답으로 응답한 경우에 발생합니다. 이는 통합 백엔드가 Amazon API Gateway에 유효하지 않은 데이터를 다시 보내고 있다는 것을 의미할 수 있습니다.

이 오류를 해결하려면 다음 작업을 수행하세요.

• Amazon API Gateway에서 요청한 내용을 재현하세요. Amazon API Gateway에서 사용하는 서비스 엔드포인트를 테스트하려면 서비스 엔드포인트 ID에 연결된 VPC 엔드포인트를 생성하세요. 또한 패킷 캡처를 실행하여 통합 백엔드에서 반환된 응답을 검토할 수 있습니다.
• 중복 암호화를 방지하려면 대상의 응답에 따라 로드 밸런서 프로토콜을 TLS 또는 TCP로 변경하세요.
• 통합 TlsConfig 속성에서 insecureSkipVerification이 true로 설정되어 있는지 확인하세요.

관련 정보

Amazon API Gateway 프라이빗 통합의 VPC 링크에 대한 이해

Amazon CloudWatch 지표를 사용한 REST API 실행 모니터링

API Gateway 프라이빗 통합을 위한 Network Load Balancer 설정