기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
프라이빗 연결 문제 해결
이 페이지에서는 프라이빗 호스팅 도구에 연결 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에서 해결되지 않고 프라이빗 연결에서를 사용하는 경우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의 구성 문제로 인해 발생합니다. 연결에 실패 상태가 있는 경우 AWS DevOps Agent는 failureMessage 필드의 이유를 설명하므로 체크리스트를 진행하기 전에 해당 필드를 읽습니다.
해결 방법
다음을 순서대로 확인합니다.
연결
failureMessage세부 정보를 읽습니다. 이 필드는 연결에 실패 상태가 있는 이유와 상태가CREATE_FAILED또는 일 때 나타나는 이유를 설명합니다.DELETE_FAILED
aws devops-agent describe-private-connection \ --name my-mcp-tool-connection
failureMessage는의 출력에도 표시됩니다list-private-connections. 필드의 이름이 원인인 경우 조치를 취합니다. 필드가 없으면 이유가 반환되지 않았으므로 나머지 검사를 계속 진행합니다.
포트 범위는 유효한 형식을 사용합니다. 각 포트 범위를 단일 포트(예:
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 핸드셰이크 실패 또는 서비스 연결 종료로 인해 연결이 재설정되거나 삭제되었음을 의미합니다.
도구에 액세스할 수 없음 메시지는 엔드포인트가 응답했지만 요청을 거부했음을 의미합니다. 이는 일반적으로 네트워크 문제가 아닌 권한 부여 또는 공급자 측 오류입니다.
공급자에 대한 요청을 완료할 수 없음 메시지는 일반적으로 프라이빗 연결을 통해 엔드포인트에 대한 요청을 완료하지 못하는 것입니다. 다음 해결 단계를 검토합니다.
VPC의 Amazon EC2 인스턴스 또는 AWS CloudShell 세션에서 요청이 성공하면 해당 테스트 환경에서 서비스에 연결할 수 있음을 확인합니다. 리소스 게이트웨이가 동일한 엔드포인트 URL, 포트, DNS 대상 또는 TLS 구성을 사용하는지는 확인되지 않습니다.
확인하는 방법
경로와 기본이 아닌 포트를 포함하여 등록한 정확한 엔드포인트 URL로 테스트를 반복합니다.
엔드포인트 URL의 포트가 프라이빗 연결의 포트 범위에 포함되어 있는지 확인합니다.
프라이빗 연결의 호스트 주소가 다른 애플리케이션 포트의 작업 또는 인스턴스 IP가 아닌 해당 포트의 TLS를 종료하는 로드 밸런서 또는 서비스로 확인되는지 확인합니다.
대상이 TLS 1.2 이상에서 HTTPS를 제공하고 예상 인증서 체인을 제공하는지 확인합니다.
리소스 게이트웨이 보안 그룹이 대상 포트에서 아웃바운드 트래픽을 허용하고 대상 보안 그룹이 해당 인바운드 트래픽을 허용하는지 확인합니다.
해결 방법
연결의 포트 범위에 엔드포인트의 포트가 포함되어 있는지 확인합니다. 프라이빗 연결은 트래픽을 생성할 때 구성한 포트 범위에서만 트래픽을 전달합니다. 포트 범위를 지정하지 않은 경우 연결은 포트 만 허용합니다
443. 연결은 설명 오류 없이 다른 포트로 트래픽을 삭제합니다. 삭제된 트래픽은 제한 시간,Unable to access tools오류 또는Could not complete request to provider.오류로 표시됩니다. 이는 일반적으로 비표준 포트(예: )의 엔드포인트에 영향을 미칩니다https://tools.example.com:8089/mcp. 동일한 VPC의 EC2 인스턴스curl에서 성공한는 이를 배제하지 않습니다.이 테스트는 프라이빗 연결을 완전히 우회합니다. 생성 후에는 포트 범위를 변경할 수 없습니다. 프라이빗 연결을 삭제하고 엔드포인트 URL의 모든 포트를 포함하는 포트 범위로 다시 생성한 다음 기능 공급자를 다시 등록합니다.리소스 게이트웨이가 대상에 전혀 도달할 수 있는지 확인합니다. 이는 대상이 다른 AWS 계정 또는 온프레미스에서 실행될 때 가장 먼저 배제해야 할 사항입니다. 서비스 관리형 모드에서 리소스 게이트웨이는 프라이빗 연결과 동일한 계정의 지정한 VPC 및 서브넷에 생성되므로 VPC에 대상에 대한 경로가 필요합니다. 활성에 도달한 연결은 게이트웨이의 네트워크 인터페이스가 생성되었고 정상임을 의미하고, 서비스에 연결할 수 있음을 의미하지는 않습니다. 연결 모드와 게이트웨이의 VPC를 확인한 다음 경로를 확인합니다.
aws devops-agent list-private-connections aws vpc-lattice list-resource-gateways
게이트웨이의 VPC에 대상에 대한 경로가 없는 경우 VPC 피어링, AWS 전송 게이트웨이 또는 가상 프라이빗 네트워크(VPN) 연결을 통해 하나를 추가하거나 자체 관리형 모드를 사용하여 게이트웨이를 대상의 계정으로 이동합니다. 프라이빗 연결 생성을 참조하세요.
작업 또는 인스턴스 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 핸드셰이크가 실패합니다. 이 경우 생성되는 오류 메시지는 공급자의 TLS 인증서를 신뢰할 수 없음을 참조하세요.
대상이 실행 중인지 확인합니다. 등록을 완료하기 전에 서비스가 작동 중이고 예상 포트에서 연결을 수락하는지 확인합니다.
공급자의 TLS 인증서를 신뢰할 수 없음
증상
기능 공급자 등록 또는 사용이 인증서 오류와 함께 실패합니다. 문구는 기능 유형에 따라 다르지만 모두 동일한 문제 클래스를 설명합니다.
Could not establish a trusted TLS connection to the provider host: its certificate could not be validated against a publicly trusted certificate authority.The server is using a self-signed TLS certificate. Use a certificate from a publicly trusted certificate authority.The server's TLS certificate could not be verified. Ensure the full certificate chain is served and issued by a publicly trusted certificate authority.The server's TLS certificate has expired. Renew the certificate.The server's TLS certificate does not match the endpoint hostname. Ensure the certificate covers the endpoint's domain.
원인
AWS DevOps 에이전트가 서비스가 제공한 인증서 체인을 검증할 수 없습니다. 일반적인 원인은 프라이빗 또는 내부 인증 기관(CA)에서 발급한 인증서, 중간 인증서가 누락된 체인, 체인에서 만료된 인증서 또는 엔드포인트 URL의 호스트 이름을 포함하지 않는 인증서입니다.
참고
이러한 메시지는 공개적으로 신뢰할 수 있는 CA에서 인증서를 요청하지만 프라이빗 CA가 지원됩니다. 해결 단계에 설명된 대로 프라이빗 연결에 체인을 제공합니다.
확인하는 방법
대상에 도달할 수 있는 Amazon EC2 인스턴스 또는 AWS CloudShell 세션에서 구성한 포트에 서비스가 제공하는 체인을 검사하고 최상위에 서명한 CA를 확인합니다.
openssl s_client -connect <your-host-address>:<port> -showcerts
내부 CA가 인증서에 서명한 경우 연결에서 체인을 제공합니다. 퍼블릭 CA가 서명한 경우 서비스가 전송하는 체인이 불완전할 수 있습니다.
해결 방법
프라이빗 CA의 인증서의 경우 프라이빗 연결에서 전체 체인을 제공합니다. 콘솔의 인증서 퍼블릭 키 또는의
certificate필드를 전체 PEM 인코딩 체인create-private-connection으로 설정합니다. 리프 인증서를 먼저 설정한 다음 모든 중간 CA 인증서를 설정하고 루트를 설정합니다. 프라이빗 연결 생성을 참조하세요.퍼블릭 CA의 인증서의 경우 전체 체인을 전송합니다. 리프만 전송하지 않고 리프 인증서와 모든 중간 인증서를 전송하도록 서비스를 구성합니다.
체인에서 만료된 인증서를 교체합니다.
인증서가 엔드포인트 URL의 호스트 이름을 포함하는지 확인합니다.
OAuth 토큰 교환에 연결할 수 없음
증상
OAuth 기반 MCP 서버(클라이언트 자격 증명 또는 3LO) 또는 프라이빗 연결을 통해 OAuth 클라이언트 자격 증명을 사용하는 원격 에이전트를 등록했지만 MCP 서버 또는 원격 에이전트 엔드포인트에 연결할 수 있더라도 토큰 교환이 실패합니다.
원인
OAuth 기반 기능 공급자의 경우 AWS DevOps 에이전트는 대상 URL(MCP 서버 또는 원격 에이전트 엔드포인트)과 교환 URL(OAuth 토큰 교환 엔드포인트)의 두 엔드포인트를 호출합니다. 단일 프라이빗 연결을 선택하면 두 엔드포인트 모두에 적용됩니다. 두 엔드포인트에 서로 다른 네트워크 경로를 통해서만 연결할 수 있는 경우 단일 프라이빗 연결을 둘 다로 라우팅할 수 없습니다.
해결 방법
두 엔드포인트 모두 동일한 경로를 통해 연결할 수 있는 경우 프라이빗 연결의 호스트 주소가 MCP 서버 또는 원격 에이전트 엔드포인트와 토큰 교환 엔드포인트로 모두 라우팅될 수 있는지 확인합니다.
엔드포인트에 서로 다른 네트워크 경로가 필요한 경우 단일 대신 엔드포인트별 필드를 사용합니다
privateConnectionName.targetUrlPrivateConnectionNameMCP 서버 또는 원격 에이전트 엔드포인트와 토큰 교환 엔드포인트exchangeUrlPrivateConnectionName에 대해를 설정합니다. 하나만 설정하면 다른 엔드포인트는 퍼블릭 인터넷을 통해 연결되며 다른 프라이빗 연결로 폴백되지 않습니다. 동일한 요청에서 엔드포인트별 이름을privateConnectionName와 결합할 수 없습니다. 다른 프라이빗 연결을 통해 엔드포인트 및 OAuth 토큰 교환 라우팅을 참조하세요.
사용 중인 프라이빗 연결은 삭제할 수 없습니다.
증상
에서 프라이빗 연결 삭제 실패 Private connection '<name>' is in use by one or more services. Deregister the services first.
원인
등록된 기능 공급자가 여전히 프라이빗 연결을 참조하는 동안에는 프라이빗 연결을 삭제할 수 없습니다. AWS DevOps Agent는 리소스를 제거하기 전에 삭제를 거부하므로 연결이 현재 상태로 유지됩니다.
해결 방법
연결을 사용하는 기능 공급자를 식별하고 더 이상 사용하지 않도록 등록을 취소하거나 업데이트합니다.
프라이빗 연결을 삭제합니다.
에이전트 스페이스에서 기능 공급자를 제거하는 것은 등록 취소와 동일하지 않습니다. 계정 수준에서 등록이 존재하므로 모든 에이전트 스페이스에서 등록을 제거한 다음 연결을 삭제하기 전에 등록을 삭제합니다.
연결을 삭제한 후에도 리소스 게이트웨이 또는 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 리전, 대상 호스트 주소 및 포트를 포함합니다.
관련 주제
