기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
프라이빗 연결 문제 해결
이 페이지에서는 프라이빗 호스팅 도구에 연결 for AWS DevOps 에이전트를 생성하거나 사용할 때 발생할 수 있는 일반적인 문제와 이를 해결하는 방법을 설명합니다. 각 섹션에서는 증상, 가장 가능성이 높은 원인 및 이를 수정하는 단계를 설명합니다.
프라이빗 연결의 작동 방식에 대한 개요는 섹션을 참조하세요프라이빗 호스팅 도구에 연결.
DNS 호스트 주소가 확인되지 않거나 트래픽이 잘못된 위치에 도달함
증상
호스트 주소의 DNS 이름을 사용하여 프라이빗 연결을 생성했지만 연결이 서비스에 연결할 수 없습니다. 이는 대상 서비스가 자체 호스팅 GitLab 인스턴스, 내부 Application Load Balancer(ALB) 또는 호스트 이름이 VPC 내에만 있는 MCP 서버인 경우에 가장 일반적입니다.
DNS 확인 실패는 DNS를 언급하는 메시지를 생성하지 않습니다. 대신 기능 공급자를 등록하거나 사용할 때 일반적인 연결성 또는 공급자 오류로 표시됩니다. 예를 들어 , Could not complete request to provider. Unable to connect to the MCP server at <endpoint>. The connection was interrupted.또는와 같은 인증 오류가 표시될 수 있습니다. 메시지가 DNS를 가리키지 않기 Authentication with provider failed. 때문에 다음 점검을 사용하여 원인을 확인합니다.
원인
기본적으로 프라이빗 연결은 퍼블릭 DNS()를 사용하여 호스트 주소를 확인합니다dnsResolution: PUBLIC. 호스트 이름에 프라이빗 호스팅 영역, Amazon Route 53 Resolver 규칙 또는 온프레미스 DNS 서버에만 레코드가 있는 경우 퍼블릭 확인이 실패하고 연결이 서비스에 도달하지 않습니다.
DNS가 원인인지 확인하는 방법
호스트 주소가 VPC 내에서만 확인되는지 확인합니다. 동일한 VPC의 Amazon EC2 인스턴스 또는 AWS CloudShell 세션에서를 실행합니다
nslookup <your-host-address>. 퍼블릭 DNS가 아닌 퍼블릭 DNS에서 확인되고 프라이빗 연결이를 사용하는 경우dnsResolution: PUBLICDNS 확인이 원인입니다.이름 대신 IP 주소로 테스트합니다. DNS 이름 대신 호스트 주소에 대상의 프라이빗 IP 주소(또는 로드 밸런서 IP)를 사용하는 프라이빗 연결을 일시적으로 생성합니다. 연결이 서비스에 도달하면 이전 장애는 네트워크 경로 또는 서비스 자체가 아닌 DNS 확인이었습니다.
해결 방법
호스트 이름이 VPC 내에서만 확인되는 경우 연결을 생성할 때 DNS 확인 모드를 VPC(
IN_VPC)로 설정합니다. 이 모드에서 호스트 주소는 VPC 컨텍스트 내에서 확인되므로 프라이빗 전용 호스트 이름이 올바르게 확인됩니다. 프라이빗 연결 생성을 참조하세요.DNS 확인 모드는 생성 시 선택되며 사용자가 제공한 호스트 주소에 적용됩니다. 생성 후에는 서비스 관리형 리소스 게이트웨이가 DNS를 확인하는 방법을 변경할 수 없으므로 올바른 모드를 미리 선택합니다. 잘못된 모드를 선택한 경우 연결을 삭제하고 올바른 모드로 다시 생성합니다.
호스트 주소에 IP 주소(DNS 이름 대신)를 지정하면 DNS 확인 모드가 적용되지 않으며 트래픽은 해당 IP로 직접 이동합니다.
설정에
IN_VPC를 사용할 수 없는 경우 호스트 주소가 대상의 프라이빗 IP 주소 또는 공개적으로 확인 가능하지만 프라이빗 IP로 전달되는 로드 밸런서의 DNS 이름을 가리킬 수 있습니다.
생성 실패에서 연결이 멈췄습니다.
증상
프라이빗 연결을 생성하면 콘솔에 상태가 연결 실패로 표시됩니다(그리고 describe-private-connection 상태가 반환됨CREATE_FAILED). 응답에는 실패에 대한 자세한 이유가 포함되지 않는 경우가 많으므로 조치를 취할 오류 메시지가 표시되지 않습니다.
원인
생성 실패는 대부분 서비스 오류가 아닌 요청 또는 VPC의 구성 문제로 인해 발생합니다. 자세한 실패 이유가 항상 표시되는 것은 아니므로 오류 메시지가 표시되지 않더라도 다음 체크리스트를 살펴봅니다.
해결 방법
다음을 순서대로 확인합니다.
포트 범위는 유효한 형식을 사용합니다. 각 포트 범위를 단일 포트(예:
443) 또는 시작 포트와 종료 포트가 서로 다른 실제 범위(예: )로 지정합니다8080-8090. 시작과 끝이 동일한 "범위"(예:443-443)는 거부됩니다. 최대 11개의 포트 범위를 지정할 수 있습니다.서브넷에 사용 가능한 IP 주소가 있습니다. 리소스 게이트웨이는 지정한 서브넷에 탄력적 네트워크 인터페이스(ENIs)를 프로비저닝합니다. 이러한 서브넷이 소진되면 생성이 실패합니다. 여유 주소 공간이 있는 서브넷을 선택합니다.
서브넷이 지원되는 가용 영역에 있습니다. Amazon VPC Lattice는 모든 가용 영역을 지원하지 않습니다. 다음을 실행하고 프라이빗 연결 생성에 나열된 지원되지 않는 영역과 비교합니다.
aws ec2 describe-subnets \ --subnet-ids <your-subnet-ids> \ --query 'Subnets[*].[SubnetId,AvailabilityZoneId]'
Amazon VPC Lattice 서비스 할당량에 도달하지 않았습니다. Amazon VPC Lattice 할당량, 특히 리소스 게이트웨이 제한을 기준으로 계정을 확인합니다.
IAM 정책 또는 SCP가 서비스 연결 역할을 차단하지 않습니다. 서비스 관리형 리소스 게이트웨이는 서비스 연결 역할을 통해 생성됩니다. 조직에 Amazon VPC Lattice 또는 Amazon EC2 API 작업을 제한하는 서비스 제어 정책(SCPs)이 있는 경우 서비스 연결 역할이 이러한 리소스를 생성하도록 허용하는지 확인합니다.
이러한 항목을 모두 확인한 후에도 연결이 계속 실패하면 AWS Support에 문의하십시오.
연결이 활성 상태이지만 연결성 오류와 함께 기능 등록에 실패함
증상
프라이빗 연결이 활성 상태에 도달했지만 이를 사용하는 기능 공급자(예: MCP 서버)를 등록하면 등록이 실패합니다. MCP 서버의 경우 오류 메시지는 연결성 검사가 어떻게 실패했는지 설명합니다. 다음 중 하나가 표시될 수 있습니다.
The MCP server at '<endpoint>' timed out while initializing the session.(유사한 변형은 리소스 나열을 의미함)Unable to connect to the MCP server at <endpoint>. The connection was interrupted. Verify the server is running and accessible, then try again.Unable to access tools from the MCP server at '<endpoint>' ...Could not complete request to provider.(로 표시될 수도 있음API error: 504)
원인
프라이빗 연결이 활성에 도달하면 VPC에 대한 네트워크 경로가 설정되었음을 확인합니다. 대상 서비스가 예상 주소 및 포트에 응답하고 있는지 확인하지 않습니다. 기능 공급자를 등록하면 AWS DevOps Agent는 엔드포인트에 연결할 수 있고 응답하는지 검증하며, 이는 잘못 구성된 대상 표면입니다. 이 메시지는 실패한 계층을 알려줍니다.
시간 초과 메시지는 연결이 수신 서비스에 도달하지 않았음을 의미합니다. 호스트 주소, 포트 또는 DNS 확인이 잘못되었거나 보안 그룹이 트래픽을 차단하는 경우가 많습니다.
연결이 중단됨 메시지는 일반적으로 TLS 핸드셰이크 실패 또는 서비스 연결 종료로 인해 연결이 재설정되거나 삭제되었음을 의미합니다.
도구에 액세스할 수 없음 메시지는 엔드포인트가 응답했지만 요청을 거부했음을 의미합니다. 이는 일반적으로 네트워크 문제가 아닌 권한 부여 또는 공급자 측 오류입니다.
공급자에 대한 요청을 완료할 수 없음 메시지는 일반적으로 프라이빗 연결을 통해 엔드포인트에 대한 요청을 완료하지 못하는 것입니다. 다음 해결 단계를 검토합니다.
해결 방법
작업 또는 인스턴스 IP가 아닌 로드 밸런서에서 DNS를 가리킵니다. 자주 발생하는 원인은 구성한 포트(예: )에서 TLS를 종료하는 로드 밸런서 대신 애플리케이션 포트(예:
8100)에서 컨테이너 작업 또는 인스턴스 IP로 확인되는 DNS 레코드 또는 호스트 주소입니다443. 호스트 주소가 대상 포트에서 실제로 HTTPS를 제공하는 엔드포인트로 확인되는지 확인합니다.서비스가 구성된 포트에서 HTTPS를 제공하는지 확인합니다. 대상은 연결의 포트 범위에 포함된 포트에서 최소 TLS 버전이 1.2인 HTTPS를 제공해야 합니다.
보안 그룹 규칙을 양방향으로 확인합니다. 리소스 게이트웨이 ENIs에 연결된 보안 그룹이 대상 포트에서 아웃바운드 트래픽을 허용하고 서비스의 보안 그룹이 해당 포트에서 인바운드 트래픽을 허용하는지 확인합니다. 트래픽은 VPC CIDR 범위 내의 Amazon VPC Lattice 데이터 영역 IPs에서 도착합니다. 보안 그룹 참조(ENI 보안 그룹을 소스로 허용)를 사용하거나 VPC CIDR에서 인바운드를 허용할 수 있습니다. 프라이빗 연결을 위한 방화벽 규칙 구성을 참조하세요.
프라이빗 CA의 전체 인증서 체인을 확인합니다. 프라이빗 인증 기관이 서비스의 TLS 인증서를 발급한 경우 연결을 생성할 때 전체 PEM 인코딩 인증서 체인을 제공합니다. 리프 인증서를 먼저 배치한 다음 중간을 배치한 다음 루트를 배치합니다. 체인이 불완전하면 네트워크 경로가 가동되더라도 TLS 핸드셰이크가 실패합니다.
대상이 실행 중인지 확인합니다. 등록을 완료하기 전에 서비스가 작동 중이고 예상 포트에서 연결을 수락하고 있는지 확인합니다.
OAuth 토큰 교환에 연결할 수 없음
증상
프라이빗 연결을 통해 OAuth 기반 MCP 서버 기능 공급자(클라이언트 자격 증명 또는 3LO)를 등록했지만 MCP 서버 엔드포인트에 연결할 수 있더라도 토큰 교환이 실패합니다.
원인
OAuth 기반 기능 공급자의 경우 AWS DevOps 에이전트는 대상 URL(MCP 서버 엔드포인트)과 교환 URL(OAuth 토큰 교환 엔드포인트)의 두 엔드포인트를 호출합니다. 단일 프라이빗 연결을 선택하면 두 엔드포인트 모두에 적용됩니다. 두 엔드포인트에 서로 다른 네트워크 경로를 통해서만 연결할 수 있는 경우 단일 프라이빗 연결을 둘 다로 라우팅할 수 없습니다.
해결 방법
두 엔드포인트 모두 동일한 경로를 통해 연결할 수 있는 경우 프라이빗 연결의 호스트 주소가 MCP 서버 엔드포인트와 토큰 교환 엔드포인트로 모두 라우팅될 수 있는지 확인합니다.
엔드포인트에 서로 다른 네트워크 경로가 필요한 경우 단일 대신 엔드포인트별 필드를 사용합니다
privateConnectionName.targetUrlPrivateConnectionNameMCP 서버 엔드포인트 및 토큰 교환 엔드포인트exchangeUrlPrivateConnectionName에 대해를 설정합니다. 하나만 설정하면 다른 엔드포인트는 퍼블릭 인터넷을 통해 연결되며 다른 프라이빗 연결로 폴백되지 않습니다. 동일한 요청에서 엔드포인트별 이름을privateConnectionName와 결합할 수 없습니다. 다른 프라이빗 연결을 통해 엔드포인트 및 OAuth 토큰 교환 라우팅을 참조하세요.
연결을 삭제한 후에도 리소스 게이트웨이 또는 ENIs가 유지됩니다.
증상
관리형 리소스 게이트웨이와 해당 ENIs 제거될 것으로 예상했지만 VPC에 계속 표시됩니다. 이로 인해 ENI 요금이 발생할 수 있으며와 같이 깨끗한 VPC에 의존하는 작업을 차단할 수 있습니다terraform destroy.
원인
관리형 리소스 게이트웨이 및 ENIs는 AWS DevOps 에이전트를 통해 프라이빗 연결을 삭제하는 경우에만 제거됩니다. 남아 있는 가장 일반적인 이유는 DeletePrivateConnection가 실제로 호출되지 않았거나 AWSAIDevOpsManaged 태그가 관리형 리소스에서 제거되어 삭제를 진행할 수 없기 때문입니다.
중요
AWS DevOps Agent는를 사용하여 관리하는 리소스(리소스 게이트웨이 및 해당 ENIs)에 태그를 지정합니다AWSAIDevOpsManaged. 서비스 연결 역할은이 태그를 전달하는 리소스에서만 작동할 수 있으므로 태그를 제거하거나 수정하지 마십시오AWSAIDevOpsManaged. 태그가 누락된 경우는 리소스를 정리할 DeletePrivateConnection 수 없으며 삭제에 실패합니다.
해결 방법
AWS DevOps 에이전트를 통해 연결을 삭제합니다. 콘솔(기능 공급자 > 프라이빗 연결 > 작업 > 제거) 또는 CLI를 사용합니다.
aws devops-agent delete-private-connection \ --name my-mcp-tool-connection
상태가 DELETE_IN_PROGRESS while AWS DevOps Agent로 변경되면 VPC에서 관리형 리소스 게이트웨이와 ENIs 제거됩니다.
삭제에 실패하면
AWSAIDevOpsManaged태그가 여전히 존재하는지 확인합니다. 리소스 게이트웨이 또는 해당 ENIs에서 태그가 제거된 경우 해당 리소스에 태그를 다시 적용한 다음 삭제를 다시 실행합니다.관리형 리소스 게이트웨이를 직접 삭제하지 마십시오. 리소스 게이트웨이는 계정에서 읽기 전용이며 AWS DevOps Agent에서 완벽하게 관리하며 Amazon VPC Lattice를 통해 직접 삭제할 수 없습니다. 프라이빗 연결을 삭제하면 제거가 트리거됩니다.
프라이빗 연결을 삭제했고 태그가 있으며 삭제가 완료된 후에도 리소스 게이트웨이 또는 ENIs가 여전히 남아 있는 경우 AWS Support에 문의하여 리소스를 조정합니다.
도움말 요청
문제에 대한 관련 섹션을 살펴보고 문제가 지속되면 AWS Support에 문의하세요. 에서 네트워크 경로를 조사할 수 있도록 프라이빗 연결 이름, 현재 상태, AWS 리전, 대상 호스트 주소 및 포트를 포함합니다.
관련 주제
