使用 Bridge to Kubernetes (VS Code)

  • 發行項

Bridge to Kubernetes 可讓您在開發電腦上執行和偵錯程式碼，但應用程式其餘部分或服務仍然連線至 Kubernetes 叢集。 在本指南中，您將了解如何使用 Bridge to Kubernetes 來重新導向 Kubernetes 叢集之間的流量，以及在開發電腦上執行的程式碼。

開始之前

本文假設您已經擁有具有微服務架構的叢集，而且您想要對叢集中的其中一個 Pod 進行偵錯。 如果您想要了解如何搭配現有的範例應用程式使用 Bridge to Kubernetes，請參閱搭配範例使用 Bridge to Kubernetes。 如果您使用 Azure Kubernetes 服務並想要使用更複雜的範例應用程式，請參閱 Bridge to Kubernetes (AKS)。

必要條件

  • 具有您要偵錯之應用程式的 Kubernetes 叢集。
  • 在 macOS、Windows 10 或更新版本或 Linux 上執行的 Visual Studio Code。

連線到您的叢集並偵錯服務

使用 Bridge to Kubernetes 開始偵錯處理序的方式有幾種不同。 如果您是從開放原始碼 Kubernetes 延伸模組開始，但未安裝 Bridge to Kubernetes，請移至安裝並使用本機通道偵錯。 如果您已安裝 Bridge to Kubernetes，請繼續進行下列步驟：

  1. 在您的開發電腦上，請確定您目前的內容已設定為執行應用程式的叢集和命名空間。

  2. 開啟您想要在 Visual Studio Code 中偵錯之應用程式的工作區。 在 [叢集] 下的 [Kubernetes 延伸模組] 檢視中，確定已選取您的叢集和命名空間。 開啟命令選擇區 (CTRL+SHIFT+P 或 Mac 上的 Cmd+Shift+P)，然後執行命令 Bridge to Kubernetes: Configure 以啟動設定流程。

  3. 選擇您想要重新導向至本機版本的 Kubernetes 服務。

    選取要連線的服務

    Kubernetes 叢集中的所有流量都會針對您的服務重新導向至開發電腦中執行的應用程式版本。 Bridge to Kubernetes 也會將應用程式的所有輸出流量路由回 Kubernetes 叢集。

    重要

    您只能重新導向具有單一 Pod 的服務。

  4. 選取服務之後，請略過下一節，然後遵循使用 Bridge to Kubernetes 設定本機通道偵錯的偵錯工具中的步驟繼續進行。

安裝和使用本機通道偵錯

當您已安裝開放原始碼 Kubernetes 延伸模組，並具有您想要偵錯之服務的 Kubernetes 叢集時，請遵循下列步驟來開始使用本機通道偵錯。 本節中的步驟將引導您完成 Bridge to Kubernetes 的安裝，並啟動本機通道偵錯的設定流程。

注意

適用於 VS Code 的 Kubernetes 延伸模組提供 API 進入點，可讓延伸模組作者從 VS Code Marketplace 貢獻其他本機通道解決方案。 Bridge to Kubernetes 是本機通道偵錯功能的其中一個可能實作。

有兩種方式可以開始在 VS Code 中使用本機通道偵錯。 第一種方式是開啟命令選擇區 (CTRL+SHIFT+P 或 Mac 上的 Cmd+Shift+P)，並輸入 Kubernetes: Debug (Local Tunnel)。

顯示 VS Code 中偵錯 (本機通道) 命令的螢幕擷取畫面

或者，瀏覽至您的 Kubernetes 叢集總管。 開啟作用中叢集的資源，並找出您想要偵錯的服務或 Pod，然後以滑鼠右鍵按一下服務，並選取 [偵錯：本機通道]。

此時，如果您沒有安裝任何提供本機偵錯功能的 VS Code 延伸模組，系統會將您重新導向至 Marketplace，以選取提供本機偵錯的延伸模組。 選取 [Bridge to Kubernetes] 延伸模組。

顯示 VS Code 中 [偵錯本機通道] 操作功能表的螢幕擷取畫面

安裝 Bridge to Kubernetes 延伸模組之後，下次選擇 [偵錯：本機通道] 時，您將略過安裝步驟，然後直接前往下一個步驟，使用 Bridge to Kubernetes 設定本機通道偵錯的偵錯工具。

使用 Bridge to Kubernetes 設定本機通道偵錯的偵錯工具

設定本機通道偵錯的偵錯工具第一個步驟是，系統會提示您輸入應用程式用來在本機執行的 TCP 連接埠：

輸入連接埠號碼

選擇您在本機執行應用程式時通常會使用的偵錯啟動設定。 如果您沒有啟動設定，您可以讓 Bridge to Kubernetes 建立一個設定，或選擇不建立，在此情況下，您必須手動啟動應用程式或服務。 若要深入了解，請參閱啟動設定。

選擇偵錯工具啟動組態

您可以選擇執行隔離或不隔離。 如果您執行隔離，則只會將要求路由傳送至本機處理序；其他開發人員可以使用叢集，而不會受到影響。 如果您沒有執行隔離，所有流量都會重新導向至本機處理序。 如需此選項的詳細資訊，請參閱使用路由功能進行隔離開發。

選擇隔離

選取左側的 [偵錯] 圖示，然後選取新增的 Kubernetes 啟動設定，例如在頂端使用 Kubernetes 透過 NPM 啟動。 如果您選擇該選項，Bridge to Kubernetes 會建立此啟動設定。

選擇偵錯啟動設定檔

注意

系統會提示您允許 EndpointManager 執行提升權限並修改主機檔案。

當 VS Code 狀態列變成橙色且 Kubernetes 延伸模組顯示您已連線時，則您的開發電腦已連線。

使用 Bridge to Kubernetes 進行偵錯

一旦開發電腦已連線，流量就會開始重新導向至您正在取代之服務的開發電腦。

注意

在後續的啟動時，系統不會提示您輸入服務名稱、連接埠、啟動工作，或是否要執行隔離。 這些值會儲存在 .vscode/tasks.json 中。 若要稍後變更這些設定，請開啟命令選擇區 (CTRL+SHIFT+P 或 Mac 上的 Cmd+Shift+P)，然後執行命令 Bridge to Kubernetes: Configure。 您可以開啟 .vscode/launch.json 和 .vscode/tasks.json，以查看 Bridge to Kubernetes 新增至啟動設定檔的特定設定。

如果您的叢集使用 gRPC C 核心，則使用 ares 的 gRPC 實作，會將環境變數新增至啟動設定檔，GRPC_DNS_RESOLVER，其值為 native。 此變數指定使用因應措施，以避免連線時發生 2 分鐘的延遲。 如需詳細資訊，請參閱此 gRPC 問題。

設定中斷點

使用 F9 設定中斷點，或選取 [執行]，然後選取 [切換中斷點]。

開啟公用 URL 以瀏覽至範例應用程式。 當您的程式碼到達中斷點時，它應該會在偵錯工具中開啟。 若要繼續服務，請按 Ctrl+F5 或選取 [執行]，然後選取 [繼續]。 返回瀏覽器，並確認您看到自行車的預留位置影像。

更新您的應用程式

當您在本機進行程式碼變更時，使用叢集的其他人是否可以看到這些變更，取決於您是否執行隔離。 如果您執行隔離，您可以進行不會影響其他使用者的變更。

編輯您的程式碼、儲存變更，然後按 Ctrl+Shift+F5 (Mac 上的 ⇧⌘F5) 或選取 [執行] 然後選取 [重新啟動偵錯]。 重新連線之後，請重新整理瀏覽器並驗證變更。

選取 [執行]，然後選取 [停止偵錯]，或按 Shift+F5 以停止偵錯工具。

注意

根據預設，停止偵錯工作也會中斷開發電腦與 Kubernetes 叢集的連線。 您可以藉由在 Visual Studio Code 設定中搜尋 Bridge to Kubernetes：偵錯之後中斷連線，並移除 [偵錯停止時自動中斷連線] 旁的核取方塊，以變更此行為。 更新此設定之後，當您停止並開始偵錯時，您的開發電腦會保持連線。 若要中斷開發電腦與叢集的連線，請按一下狀態列上的 [Bridge to Kubernetes 延伸模組]，然後選擇 [中斷目前工作階段的連線]。

其他設定

Bridge to Kubernetes 可以處理路由流量和複寫環境變數，而不需要任何其他設定。 如果您需要下載任何掛接至 Kubernetes 叢集中容器的檔案，例如 ConfigMap 檔案，您可以建立 KubernetesLocalProcessConfig.yaml 以將這些檔案下載到您的開發電腦。 如需詳細資訊，請參閱設定 Bridge to Kubernetes。

如果您使用的是使用受控識別的 AKS 叢集，Microsoft Entra ID 所提供的安全性功能，請參閱 搭配 Bridge to Kubernetes 使用受控識別，以取得如何針對此案例設定 Bridge to Kubernetes 的相關資訊。

使用記錄和診斷

當您的開發電腦連線到 Kubernetes 叢集之後，會將記錄輸出寫入至 [Bridge to Kubernetes] 視窗。

按一下 [Kubernetes] 狀態列，然後選擇 [顯示連線診斷資訊]。 此命令會在記錄輸出中列印目前的環境變數和 DNS 整體。

此外，您可以在開發電腦 TEMP 目錄的 Bridge to Kubernetes 目錄中找到診斷記錄。 在 Windows 10 上，也就是在 %TEMP%\Bridge to Kubernetes 中。 在 Mac 上，您可以從終端視窗執行 echo $TMPDIR 來找到 TEMP 目錄。 在 Linux 上，是 /tmp/Bridge to Kubernetes。

以隔離模式執行

使用 Bridge to Kubernetes，您也可以設定所處理服務的隔離版本，這表示使用叢集的其他人不會受到變更的影響。 此隔離模式是透過將要求路由傳送至每個受影響的服務複本來完成，但通常會路由傳送所有其他流量。 若要存取隔離應用程式的本機端點 URL，請以隔離模式啟動偵錯工具、開啟狀態列上的 [Kubernetes] 功能表，然後選擇端點項目。 您可以在 Bridge to Kubernetes 的運作方式中找到路由在隔離模式中運作方式的詳細資訊。

標頭傳播

若要使用 Bridge to Kubernetes 的設計方式，您必須確定將 Bridge to Kubernetes 標頭從連入要求傳播到服務對叢集中其他服務所做的任何要求。 不論語言為何，所有 HTTP 要求 API 都會提供一些特定架構的方式來執行這項操作。 例如，針對 C# 中的 .NET 程式碼，您可以使用類似下列的程式碼：

var request = new HttpRequestMessage();
request.RequestUri = new Uri("http://mywebapi/api/values/1");
if (this.Request.Headers.ContainsKey("kubernetes-route-as"))
{
    // Propagate the dev space routing header
    request.Headers.Add("kubernetes-route-as", this.Request.Headers["kubernetes-route-as"] as IEnumerable<string>);
}
var response = await client.SendAsync(request);

注意

若要避免在每個要求影響程式碼，您可以建立繼承自 System.Net.Http.DelegatingHandler 的類別，並使用類似上述範例的程式碼覆寫 SendAsync 方法。 您可以在 Web 上使用這項技術來尋找程式碼; 其中一個範例是 正確傳播 Bridge to Kubernetes 中的 「kubernetes-route-as」。

針對 Node.js 服務，您可以使用類似下列的程式碼，從橋接至 Kubernetes 存放庫中的 todo-app 範例取得：

    server.get("/api/stats", function (req, res) {
        var options = {
            host: process.env.STATS_API_HOST,
            path: '/stats',
            method: 'GET'
        };
        const val = req.get('kubernetes-route-as');
        if (val) {
            console.log('Forwarding kubernetes-route-as header value - %s', val);
            options.headers = {
                'kubernetes-route-as': val
            }
        }
        var req = http.request(options, function(statResponse) {
            res.setHeader('Content-Type', 'application/json');
            var responseString = '';
            //another chunk of data has been received, so append it to `responseString`
            statResponse.on('data', function (chunk) {
                responseString += chunk;
            });
            statResponse.on('end', function () {
                res.send(responseString);
            });
        });

        req.on('error', function(e) {
            console.log('problem with request: ' + e.message);
          });

          req.end();
    });

與其他服務通訊

當您與相同 Kubernetes 叢集中的另一個服務通訊時，例如使用 HTTP 要求，您通常會在要求的 URL 中使用硬式編碼服務名稱，但在某些情況下將無法運作，例如使用遠端 SSH、WSL 和 GitHub Codespaces 時。 本文說明如何使用 Kubernetes 服務環境變數來指定這些案例的連線 URL。

疑難排解

如果您在啟用 Bridge to Kubernetes延伸模組時收到此錯誤：

「無法更新相依性：超過重試次數上限」

首先，使用按鈕重試啟用。 如果重複失敗，請參閱https://github.com/microsoft/mindaro/issues/32。

當您在遠端 SSH 工作階段中使用 Bridge to Kubernetes 時，如果 EndpointManager 失敗，問題可能是 Bridge to Kubernetes 因權限問題而無法修改主機檔案。 若要啟用遠端 SSH 或以非提高權限的使用者身分執行，您應該更新程式碼以使用 Kubernetes 服務環境變數，並設定 VS Code 以使用它們，如服務環境變數主題中所述。

下一步

若要深入了解 Bridge to Kubernetes，請參閱 Bridge to Kubernetes 的運作方式。

如果您需要同時對多個服務進行偵錯，請參閱 同時偵錯多個服務。

在 Bridge to Kubernetes 藍圖中找到目前支援功能和未來 Kubernetes 藍圖的相關資訊。