使用 Cloud Code for VS Code 调试 Kubernetes 应用

借助 Cloud Code,您可以使用 skaffold debug 调试部署到 Google Kubernetes Engine (GKE) 集群的应用。

您可以在本地集群(如 minikubeDocker Desktop)、GKE 或任何其他云服务商上调试应用。

借助 Cloud Code 的调试支持,您无需完成手动设置,例如设置端口转发或注入特定于语言的调试参数。调试需要一个支持 Cloud Code 的 GKE 应用,其中包含 skaffold.yaml 配置文件和 cloudcode.kubernetes 启动配置。

调试 GKE 应用

如需开始调试您的 GKE 应用,请按以下步骤操作:

  1. 在 Cloud Code 状态栏中,点击活跃项目名称。

    状态栏中显示有效项目名称

  2. 在随即显示的“快捷选择”菜单中,选择在 Kubernetes 上调试

  3. 如果出现提示,请对您的凭据进行身份验证,以在本地运行和调试应用

  4. 如果您的应用没有必要的 Skaffold 配置或 cloudcode.kubernetes 启动配置,Cloud Code 可帮助您进行设置

  5. 确认是否使用当前 Kubernetes 上下文运行应用(或切换到首选上下文)。

  6. 如果您选择了远程集群作为上下文,请在出现提示时选择将映像推送到其中的映像注册数据库。如果您使用的是 Container Registry,则可以浏览至现有注册数据库,或指定要创建的注册数据库的名称。如果您的项目已启用 Artifact Registry API 并且至少有一个 Artifact Registry 代码库,则可以浏览并选择现有的 Artifact Registry 代码库。

    以下示例展示了如何为一些常用的注册表指定容器映像的存储位置:

    Artifact Registry {region}-docker.pkg.dev/{project_id}/{repo-name}
    Container Registry gcr.io/{project_id}
    Docker Hub docker.io/{account}
    如果您使用的是专用 Docker Hub 代码库,请确保已正确进行身份验证
    AWS Container Repository (ECR) {aws_account_id}.dkr.ecr.{region}.amazonaws.com/{my-app}
    Azure Container Registry (ACR) {my_acr_name}.azurecr.io/{my-app}

    如需生成最终映像存储库名称,Cloud Code 会将此映像注册表与 Kubernetes 清单中指定的映像名称进行连接。此选项会存储在您的 cloudcode.kubernetes 启动配置(可在 .vscode/launch.json 中找到)中。

    如需了解详情,请参阅映像注册表处理指南

    Cloud Code 会构建您的容器,将其推送到注册表,将 Kubernetes 配置应用到集群,并等待发布。

    发布完成后,Cloud Code 会自动将所有声明的容器端口转发到您的机器,并在输出窗口中显示网址,以便您可以浏览正在运行的应用。

  7. 对于应用中的每个可调试容器,确认或输入您要调试的程序所在的远程容器目录。

    或者,您可以按 ESC 跳过调试容器。

    远程根目录提示

    Cloud Code 会为应用中的每个可调试容器附加调试会话。

    现在您可以执行在调试本地代码时通常会执行的任务,例如针对实时 Kubernetes 集群设置断点和单步执行代码。

    默认情况下,当您保存对应用的更改时,Cloud Code 会重新部署应用并设置新的调试会话。您可以使用项目的启动配置中的 watch 标志切换此功能。

  8. 如需检查变量和堆栈信息,请使用调试边栏。 如需与调试会话进行交互,请使用底部窗格调试器中的调试控制台

  9. 会话完成后,您可以使用以下上下文菜单命令:

    • 打开部署日志:使用 Cloud Code Logs Explorer 打开特定部署的应用日志。
    • 打开服务网址:在 Web 浏览器中打开特定服务的应用服务网址
  10. 如果您在启动配置中关闭了观看模式,并且想要更改应用并重新构建并重新部署应用,请在“Development sessions”(开发会话)窗格中暂停执行操作,然后点击 “重新构建和重新部署”图标 Rebuild and redeploy the application(重新构建并重新部署应用)。

  11. 如需结束调试会话,请点击调试工具栏中的 调试停止图标 停止

    结束调试会话后,所有部署的 Kubernetes 资源都会从集群中删除。

配置详情

Skaffold 提供支持的 Cloud Code 会自动处理所有受支持语言的以下配置详情:

  • 对调试端口执行端口转发,以便连接调试器。
  • 将调试器连接到应用中的一个或多个可调试容器。 如果您的应用在 skaffold.yaml 中配置了多个可调试容器(Cloud Code 调试支持其语言的容器),则系统会为每个可调试容器连接一个调试程序。
  • 跨会话保留来源映射定义;您可以通过直接修改 .vscode/launch.json 文件来自定义这些定义。

Cloud Code 还会处理以下特定于语言的配置详细信息:

Node.js

重写要调用的入口点:

node --inspect=localhost:9229

Python

使用 Init 容器安装 ptvsd 模块并重写要调用的入口点:

python -m ptvsd --host localhost --port 5678

Go

使用 init 容器安装 dlv 调试程序并重写入口点,以便启动的调试会话仅使用调试服务器运行(在无头模式下),在启动时继续调试的进程,接受多个客户端连接,并侦听 localhost:56268

  dlv exec --headless --continue --accept-multiclient --listen=localhost:56268 --api-version=2, <app> --

Java

使用适当的 Java 调试连接协议 (JDWP) 配置添加环境 JAVA_TOOLS_OPTIONS,以便 JDWP 调试代理在端口 5005 上侦听套接字连接,并允许虚拟机在连接调试程序之前开始执行:

  jdwp=transport=dt_socket,server=y,suspend=n,address=5005,quiet=y

如需详细了解由 Skaffold 支持的调试,请参阅 skaffold debug 文档

设置您的容器

如需准备容器以进行调试,请按照您使用的语言的相关说明进行操作:

Node.js

  • 使用 --inspect=<debugPort> 启动 Node.js 应用,其中 debugPort 来自连接配置。例如:CMD ["node", "--inspect=9229", "index.js"]

Python

  • 确保您的机器和容器中已安装 ptvsd 模块。
  • 通过 ptvsd 启动 Python 应用。将指定的端口与连接配置中的 debugPort 字段进行匹配。例如:
    CMD ["python", "-m", "ptvsd", "--port", "", "app.py"]
    

Go

  • 确保您的机器和 Go 容器中已安装 dlv 软件包。
  • 通过 dlv debug 启动 Go 应用。

    启动命令中指定的端口应与连接配置中的 debugPort 属性值相同。例如:

    CMD ["dlv", "debug", "--headless", "--listen=:<debugPort>", "--log"]
    

    问题排查提示:调试 Go 应用时,应用将停止并等待连接调试程序。请连接调试器以使该服务启动。

Java

  • 确保您的机器上已安装 JVM。
  • 使用以下选项启动 Java 应用,其中 debugPort 来自连接配置

    -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=,quiet=y
    

    例如,如需在调试模式下启动 Java 应用,并侦听端口 debugPort 上的连接,请使用以下语句:

    ENTRYPOINT ["java","-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=<debugPort>,quiet=y", "-jar", "my-app-1.0.jar"]
    

.NET Core

  • 确保您的 Kubernetes 容器上已安装 vsdbg(Microsoft 提供的 .NET Core 命令行调试程序)。

    例如:

    RUN apt-get update 
    && apt-get install -y --no-install-recommends unzip
    && apt-get install -y procps
    && rm -rf /var/lib/apt/lists/*
    && curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /dbg/netcore/vsdbg

设置连接配置

如需附加到可调试容器,您需要有一个 cloudcode.kubernetes 类型的附加配置

添加 .vscode/launch.json 文件

如果项目的 .vscode 文件夹中没有 launch.json 文件,您可以使用“调试”面板添加一个。

  1. 如需前往“调试”面板,请点击 Activity 栏中的 “调试”图标 Run and Debug

  2. 从下拉菜单中选择 Add Configuration

  3. Cloud Code Kubernetes 设置为环境。

    将 Cloud Code Kubernetes 设置为环境

  4. 选择连接到 Kubernetes Pod 选项。

    选择 Kubernetes 配置选项

  5. 选择您所使用的编程语言。

    这将为您的项目创建并打开 launch.json 文件,并为您创建连接配置。

  6. 更新 launch.json 文件中的配置属性,以匹配项目的配置属性。如需详细了解配置属性,请参阅配置属性

将连接配置添加到 .vscode/launch.json 文件中

如需向现有 .vscode/launch.json 文件添加新的连接配置,请执行以下操作:

  1. 打开 launch.json 文件。
  2. 如要调用代码段 Intellisense,请点击添加配置
  3. 如需添加连接配置,请针对您使用的语言选择 Cloud Code: Attach to Kubernetes Pod 代码段。
  4. 请更新配置中的属性,使其与项目的属性相匹配。如需详细了解配置属性,请参阅配置属性

配置属性

属性 说明
debugPort 容器中使用的调试端口。
podSelector 用于选择调试 Pod 的一组键值对。如需了解详情,请参阅选择器指南。 以下示例展示了典型的 podSelector

"podSelector": { "app": <deployment-name> }
localRoot 包含待调试程序的本地目录的路径。 默认为 ${workspaceFolder}。
remoteRoot 包含待调试程序的远程目录的绝对路径(在 Kubernetes 容器中)。

将调试程序连接到 Kubernetes Pod

Cloud Code for VS Code 支持将调试程序连接到适用于 Node.js、Python、Go、Java 和 .NET 的 Kubernetes Pod。您只需要一个可调试的容器cloudcode.kubernetes 类型的连接配置

如需了解附加到 Kubernetes Pod 与调试 Kubernetes 应用有何不同,请参阅将调试程序连接到 Pod 与调试 Kubernetes 应用有何不同

如需将调试程序连接到 Kubernetes Pod,请执行以下任务:

  1. 如需前往“调试”面板,请点击 Activity 栏中的 “调试”图标 Run and Debug
  2. F5 选择并启动配置。

    • 在调试时,localhost:${debugPort} 通过端口转发到容器上的 debugPort

    调试会话现已成功设置。您可以执行在调试本地代码时通常会执行的任务,例如设置断点和单步调试代码。

  3. 如需检查变量和堆栈信息,请使用调试边栏。 如需与调试会话进行交互,请使用底部窗格调试器中的调试控制台

  4. 如需结束调试会话,请点击调试工具栏中的 调试停止图标 停止

将调试程序连接到 Pod 与调试 Kubernetes 应用有何不同

挂接到 Kubernetes Pod 调试 Kubernetes 应用
调试单个 Kubernetes pod。 调试应用中所有可调试的容器。
应用必须在 Kubernetes Pod 中运行才能进行调试。 在 Kubernetes 集群上运行应用并附加调试程序。
使用 cloudcode.kubernetes 类型的配置 (.vscode/launch.json) 并请求 attach 使用 cloudcode.kubernetes 类型的配置 (.vscode/launch.json) 并请求 launch
如需了解详情,请参阅启动配置与连接配置
配置示例:

{
  "name": "Attach to Kubernetes Pod (NodeJS)",
  "type": "cloudcode.kubernetes",
  "request": "attach",
  "language": "Node",
  "debugPort": 9229,
  "podSelector": {
     "app": "hello-world"
  },
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/app"
}
配置示例:

{
  "name": "Run/Debug on Kubernetes",
  "type": "cloudcode.kubernetes",
  "request": "launch",
  "skaffoldConfig": "${workspaceFolder}/skaffold.yaml",
  "watch": true,
  "cleanUp": true,
  "portForward": true
}
此配置不能用于运行应用。 此配置可用于运行或调试应用。
此配置特定于语言。 此配置与语言无关。
无专用命令。 Debug on Kubernetes 命令。
Watch 模式不可用,因此进行更改后,请手动重启调试程序。 Watch 模式允许 Cloud Code 在您保存更改后重启调试程序。

后续步骤

获取帮助

如需发送反馈,请在 GitHub 上报告问题,或者在 Stack Overflow 上提问。