使用 Bridge to Kubernetes (VS Code)

项目
02/11/2025

说明

Bridge to Kubernetes 将于 2025 年 4 月 30 日停用。有关停用和开源替代项的详细信息，请参阅 GitHub 问题。

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，请继续执行以下步骤：

在开发计算机上，请确保当前上下文设置为运行应用程序的群集和命名空间。
打开要在 Visual Studio Code 中调试的应用的工作区。在群集下的 Kubernetes 扩展视图中，确保已选择群集和命名空间。打开命令面板（CTRL+SHIFT+P 或 Cmd+Shift+Mac 上的 P），并运行命令 Bridge to Kubernetes：配置 以启动配置过程。
选择要重定向到本地版本的 Kubernetes 服务。

的服务

Kubernetes 群集中服务的所有流量都会重定向到开发计算机中运行的应用程序版本。 Bridge to Kubernetes 还会将应用程序的所有出站流量路由回 Kubernetes 群集。

重要

只能重定向仅有一个 pod 的服务。
选择服务后，请跳过下一部分，然后继续执行步骤配置调试器以使用 Bridge to Kubernetes 进行本地隧道调试步骤。

安装和使用本地隧道调试

如果已安装开放源代码 Kubernetes 扩展并安装了包含要调试的服务的 Kubernetes 群集，请按照以下步骤开始使用本地隧道调试。本部分中的步骤将引导你完成 Bridge to Kubernetes 的安装，并启动本地隧道调试的配置过程。

备注

适用于 VS Code 的 Kubernetes 扩展提供了一个 API 入口点，该入口点允许扩展作者从 VS Code 市场贡献其他本地隧道解决方案。 Bridge to Kubernetes 是本地隧道调试功能的一种可能实现。

可通过两种方法开始在 VS Code 中使用本地隧道调试。第一种方法是打开命令面板（在 Windows 上按CTRL+SHIFT+P 或在 Mac 上按 Cmd+Shift+P），并键入 Kubernetes: 调试（本地隧道）。

显示 VS Code屏幕截图

也可导航到 Kubernetes 群集资源管理器。打开活动群集的资源，找到要调试的服务或 pod，然后右键单击该服务，接着选择调试：本地隧道。

此时，如果没有安装提供本地调试功能的任何 VS Code 扩展，则会重定向到市场以选择提供本地调试的扩展。选择“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 或 Cmd+Cmd+P 在 Mac 上），并运行命令 Bridge to Kubernetes：配置。可以打开 .vscode/launch.json，.vscode/tasks.json 以查看 Bridge to Kubernetes 添加到启动配置文件的特定配置设置。

如果您的群集使用 gRPC C 核心，这是一个使用 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 服务，你可以使用类似于以下的代码，该代码取自 Bridge to 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 和 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 (VS Code)

开始之前

先决条件

连接到群集并调试服务

安装和使用本地隧道调试

使用 Bridge to Kubernetes 为本地隧道调试配置调试器

设置断点

更新应用程序

其他配置

使用日志记录和诊断

在隔离模式下运行

标头传播

与其他服务通信

故障排除

后续步骤

反馈

其他资源

通过

使用 Bridge to Kubernetes (VS Code)

开始之前

先决条件

连接到群集并调试服务

安装和使用本地隧道调试

使用 Bridge to Kubernetes 为本地隧道调试配置调试器

设置断点

更新应用程序

其他配置

使用日志记录和诊断

在隔离模式下运行

标头传播

与其他服务通信

故障 排除

后续步骤

反馈

其他资源

故障排除