API Gateway REST API와 VPC 링크 통합을 사용할 때 500 오류를 해결하려면 어떻게 해야 합니까?

간략한 설명

VPC 링크 통합이 포함된 API Gateway는 트래픽을 백엔드 리소스로 전달하지 못할 수 있습니다.

다음과 같은 이유 중 하나로 인해 ‘HTTP 500’ 상태 코드를 반환할 수도 있습니다.

• VPC 링크가 실패 상태입니다. 또는 엔드포인트 서비스가 존재하지 않거나 거부됨 상태입니다.
• 대상 그룹에 등록된 대상이 비정상이거나 사용 중이 아닌 것으로 표시됩니다.
• 보안 그룹은 특정 포트의 트래픽을 허용하지 않습니다.
• 네트워크 액세스 제어 목록(네트워크 ACL)은 트래픽을 차단합니다.
• 대상이 대상 포트에서 수신 대기하지 않습니다.
• 도메인 이름 인증서가 TLS 활성화 Network Load Balancer 또는 Application Load Balancer와 일치하지 않습니다.

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

해결 방법

백엔드 연결 검증

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’ 문제 해결

다음 오류 메시지가 표시됩니다.

"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’ 문제 해결

다음 오류 메시지가 표시됩니다.

"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 Gateway는 다음 정보를 검토합니다.

• 인증서 만료 날짜
• 호스트 이름
• 루트 인증 기관(CA)의 존재 여부
  참고: 통합 시 API Gateway가 신뢰 체인을 확인하고 보안 연결을 수립하기 위한 전체 인증서 체인을 포함하고 반환해야 합니다. 전체 체인은 서버 인증서부터 루트 CA 인증서에 이르기까지 모든 중간 인증서를 포함합니다. 또한 루트 CA에는 keyCertSign을 사용한 keyUsage와 CA:TRUE를 사용하는 basicConstraints가 포함되어야 합니다. 자세한 내용은 x-amazon-apigateway-integration.tlsConfig 객체를 참조하십시오.

‘Cannot verify ECDH ServerKeyExchange signature’ 문제 해결

다음 오류 메시지가 표시됩니다.

"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’ 문제 해결

다음 오류 메시지가 표시됩니다.

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

API Gateway에는 많은 종속성이 있습니다. 종속성 중 하나에 일시적인 연결 실패가 있는 경우 오류가 발생할 수 있습니다. 빈도가 낮은 오류의 경우 지수 백오프를 사용하여 재시도를 구현하는 것이 좋습니다. 오류 빈도가 높은 경우에는 AWS Support에 문의하십시오. 오류가 표시되는 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 및 IntegrationLatency API Gateway 지표를 모니터링하여 패턴을 감지합니다.
• AWS X-Ray 추적을 활성화하여 API Gateway에서 VPC 링크로, VPC 링크에서 Network Load Balancer로, Network Load Balancer에서 백엔드로 향하는 요청 경로를 모니터링할 수 있습니다.

관련 정보

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

Amazon CloudWatch 지표로 REST API 실행 모니터링

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