View a markdown version of this page

對私有連線進行故障診斷 - AWS DevOps 代理程式
DNS 主機地址無法解析，或流量到達錯誤的位置連線卡在建立失敗連線為作用中，但功能註冊失敗並出現連線能力錯誤提供者的 TLS 憑證不受信任無法連線 OAuth 權杖交換私有連線在使用中時無法刪除在您刪除連線後，資源閘道或 ENIs仍會保留請求協助相關主題

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

對私有連線進行故障診斷

此頁面說明您在建立或使用 連線至私有託管工具 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.或 等身分驗證錯誤，Authentication with provider failed.因為訊息不會指向 DNS，請使用下列檢查來確認原因。

原因

根據預設，私有連線會使用公有 DNS () 解析主機地址dnsResolution: PUBLIC。如果您的主機名稱在私有託管區域中只有記錄、Amazon Route 53 Resolver 規則或內部部署 DNS 伺服器，則公有解析會失敗，且連線永遠不會到達您的服務。

如何確認 DNS 是原因

  • 檢查您的主機地址是否只在 VPC 內解析。從相同 VPC 中的 Amazon EC2 執行個體或 AWS CloudShell 工作階段，執行 nslookup <your-host-address>。如果它在那裡解析，但不是從公有 DNS 解析，而且您的私有連線使用 dnsResolution: PUBLIC，則 DNS 解析是原因。

  • 使用 IP 地址而非名稱進行測試。暫時建立私有連線，使用目標的私有 IP 地址 （或負載平衡器 IP) 做為主機地址，而非 DNS 名稱。如果連線接著到達您的服務，則先前的失敗是 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 代理程式會在 failureMessage 欄位中說明原因，因此請先閱讀該欄位，再處理檢查清單。

解決方案

依序驗證下列項目：

  1. failureMessage讀取連線的詳細資訊。此欄位說明連線為何具有失敗狀態，且當狀態為 CREATE_FAILED或 時存在DELETE_FAILED：

aws devops-agent describe-private-connection \ --name my-mcp-tool-connection

failureMessage 也會出現在 的輸出中list-private-connections。如果欄位為原因命名，請對其採取行動。如果 欄位不存在，則不會傳回任何原因，因此請繼續剩餘的檢查。

  1. 連接埠範圍使用有效的格式。將每個連接埠範圍指定為單一連接埠 （例如 443) 或具有不同開始和結束連接埠的真正範圍 （例如 8080-8090)。開始和結束相同 （例如 443-443) 的「範圍」會遭到拒絕。您最多可以指定 11 個連接埠範圍。

  2. 您的子網路具有可用的 IP 地址。資源閘道會在您指定的子網路中佈建彈性網路介面 (ENIs)。如果這些子網路用盡，建立會失敗。選擇具有可用地址空間的子網路。

  3. 您的子網路位於支援的可用區域。Amazon VPC Lattice 不支援每個可用區域。執行下列動作，並與建立私有連線 中列出的不支援區域進行比較：

aws ec2 describe-subnets \ --subnet-ids <your-subnet-ids> \ --query 'Subnets[*].[SubnetId,AvailabilityZoneId]'

  1. 您尚未達到 Amazon VPC Lattice 服務配額。檢查您的帳戶是否符合 Amazon VPC Lattice 配額，尤其是資源閘道限制。

  2. 沒有 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)

原因

到達 Active 的私有連線會確認 VPC 的網路路徑已建立。它不會確認您的目標服務在預期的地址和連接埠上回應。當您註冊功能提供者時， AWS DevOps 代理程式會驗證端點是否可連線和回應，而這是設定錯誤的目標表面。訊息會告訴您哪個 layer 失敗：

  • 逾時訊息表示連線從未到達接聽服務。連線的連接埠範圍通常不包含端點的連接埠、主機地址或 DNS 解析錯誤，或安全群組封鎖流量。

  • 連線中斷訊息表示連線已重設或捨棄，通常是由於 TLS 交握失敗或服務關閉連線。

  • 無法存取工具訊息表示端點已回應但拒絕請求。這通常是授權或供應商端錯誤，而不是網路問題。

  • 答 無法完成對提供者訊息的請求，是無法透過私有連線完成對端點的請求的一般失敗。檢閱接下來的解決步驟。

來自 VPC 中 Amazon EC2 執行個體或 AWS CloudShell 工作階段的成功請求會確認可從該測試環境存取服務。它不會確認資源閘道使用相同的端點 URL、連接埠、DNS 目標或 TLS 組態。

確認方式

  1. 使用您註冊的確切端點 URL 重複測試，包括其路徑和任何非預設連接埠。

  2. 確認端點 URL 的連接埠包含在私有連線的連接埠範圍中。

  3. 確認私有連線的主機地址解析為終止該連接埠上 TLS 的負載平衡器或服務，而不是其他應用程式連接埠上的任務或執行個體 IP。

  4. 確認目標使用 TLS 1.2 或更新版本提供 HTTPS，並呈現預期的憑證鏈。

  5. 確認資源閘道安全群組允許目標連接埠上的傳出流量，且目標安全群組允許對應的傳入流量。

解決方案

  • 確認連線的連接埠範圍包含端點的連接埠。私有連線只會轉送您在建立連接埠範圍時所設定的流量。如果您未指定連接埠範圍，連線只允許連接埠 443。連線會將流量捨棄至任何其他連接埠，而不會發生描述性錯誤。捨棄的流量會呈現為逾時、Unable to access tools錯誤或Could not complete request to provider.錯誤。這通常會影響非標準連接埠上的端點 （例如 https://tools.example.com:8089/mcp)。來自相同 VPC 中 curl EC2 執行個體的成功並不會排除此問題，測試會完全略過私有連線。您無法在建立之後變更連接埠範圍。刪除私有連線，使用包含端點 URL 中每個連接埠的連接埠範圍重新建立，然後再次註冊功能提供者。

  • 確認資源閘道完全可以到達您的目標。這是當目標在不同 AWS 帳戶或內部部署中執行時，要排除的第一件事。在服務受管模式中，資源閘道會在您指定的 VPC 和子網路中建立，位於與私有連線相同的帳戶中，因此 VPC 需要路由至您的目標。到達作用中的連線僅表示閘道的網路介面已建立且運作狀態良好；並不表示它們可以到達您的服務。檢查連線的模式和閘道的 VPC，然後確認路由：

aws devops-agent list-private-connections aws vpc-lattice list-resource-gateways

如果閘道的 VPC 沒有通往目標的路由，請透過 VPC 對等互連、 AWS Transit Gateway 或虛擬私有網路 (VPN) 連線新增，或使用自我管理模式將閘道移至目標的帳戶。請參閱建立私有連線。

  • 將 DNS 指向負載平衡器，而非任務或執行個體 IP。常見原因是 DNS 記錄或主機地址，可解析為應用程式連接埠 （例如 8100) 上的容器任務或執行個體 IP，而不是在您設定的連接埠 （例如 ) 上終止 TLS 的負載平衡器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 欄位create-private-connection設定為完整的 PEM 編碼鏈：先是分葉憑證，再是所有中繼 CA 憑證，再是根。請參閱建立私有連線。

  • 對於來自公有 CA 的憑證，請傳送完整的鏈結。將您的服務設定為傳送分葉憑證加上所有中繼憑證，而不是單獨傳送分葉。

  • 取代鏈結中任何過期的憑證。

  • 確認憑證涵蓋端點 URL 中的主機名稱。

無法連線 OAuth 權杖交換

徵狀

您已透過私有連線註冊以 OAuth 為基礎的 MCP 伺服器 （用戶端登入資料或 3LO) 或使用 OAuth 用戶端登入資料的遠端代理程式，但即使 MCP 伺服器或遠端代理程式端點可存取，權杖交換仍會失敗。

原因

對於以 OAuth 為基礎的功能提供者， AWS DevOps 代理程式會呼叫兩個端點：目標 URL (MCP 伺服器或遠端代理程式端點） 和交換 URL (OAuth 字符交換端點）。當您選取單一私有連線時，它會套用到兩個端點。如果兩個端點只能透過不同的網路路徑連接，則單一私有連線無法路由到兩者。

解決方案

  • 如果兩個端點都可以透過相同路徑連線，請確保私有連線的主機地址可以路由到 MCP 伺服器或遠端代理程式端點和字符交換端點。

  • 如果端點需要不同的網路路徑，請使用每個端點欄位，而不是單一 privateConnectionName。targetUrlPrivateConnectionName 為 MCP 伺服器或遠端代理程式端點設定 ，exchangeUrlPrivateConnectionName並為字符交換端點設定 。如果您只設定一個端點，則會透過公有網際網路到達另一個端點，而不會回到另一個私有連線。您無法在相同的請求privateConnectionName中結合每個端點名稱與 。請參閱透過不同的私有連線路由端點和 OAuth 權杖交換。

私有連線在使用中時無法刪除

徵狀

使用 刪除私有連線失敗 Private connection '<name>' is in use by one or more services. Deregister the services first.

原因

當已註冊的功能提供者仍參考私有連線時，無法刪除該連線。 AWS DevOps 代理程式會在移除任何資源之前拒絕刪除，因此您的連線會保持在目前的狀態。

解決方案

  1. 識別使用連線的功能提供者，並取消註冊或更新它們，使其不再使用它。

  2. 刪除私有連線。

從客服人員空間移除功能提供者與取消註冊不同。註冊存在於帳戶層級，因此請將其從所有客服人員空間中移除，然後在刪除連線之前刪除註冊。

在您刪除連線後，資源閘道或 ENIs仍會保留

徵狀

您預期會移除受管資源閘道及其 ENIs，但它們仍會出現在您的 VPC 中。這可能會產生 ENI 費用，並封鎖依賴於乾淨 VPC 的操作，例如 terraform destroy。

原因

只有在您透過 AWS DevOps 代理程式刪除私有連線時，才會移除受管資源閘道和 ENIs。其保留的最常見原因是DeletePrivateConnection從未實際呼叫 ，或AWSAIDevOpsManaged標籤已從受管資源中移除，因此無法繼續刪除。

重要

AWS DevOps Agent 會使用 標記其管理的資源 （資源閘道及其 ENIs)AWSAIDevOpsManaged。服務連結角色只能對帶有此標籤的資源採取行動，因此請勿移除或修改AWSAIDevOpsManaged標籤 。如果標籤遺失， DeletePrivateConnection無法清除資源，且刪除失敗。

解決方案

  • 透過 AWS DevOps Agent 刪除連線。使用 主控台 (功能提供者 > 私有連線 > 動作 > 移除) 或 CLI：

aws devops-agent delete-private-connection \ --name my-mcp-tool-connection

狀態會變更為 ，DELETE_IN_PROGRESS而 AWS DevOps 代理程式會從 VPC 中移除受管資源閘道和 ENIs。

  • 如果刪除失敗，請確認AWSAIDevOpsManaged標籤仍然存在。如果標籤已從資源閘道或其 ENIs中移除，請將其重新套用至這些資源，然後再次執行刪除。

  • 請勿嘗試直接刪除受管資源閘道。資源閘道在您的帳戶中為唯讀，並由 AWS DevOps 代理程式完全管理，您無法透過 Amazon VPC Lattice 自行刪除。刪除私有連線會觸發其移除。

  • 如果您刪除私有連線，且標籤存在，且在刪除完成後資源閘道或 ENIs 仍然保留，請聯絡 AWS Support 以協調資源。

請求協助

如果您處理問題的相關區段，但問題仍然存在，請聯絡 AWS Support。包含您的私有連線名稱、其目前狀態、 AWS 區域，以及目標主機地址和連接埠，以便支援可以調查網路路徑。