在本地构建和调试

本页面介绍如何在本地机器上使用 Cloud Build。使用本地构建器,您可以:

  • 在本地计算机上更快地迭代构建。
  • 使用试运行 lint 配置文件。

本地构建器只能在 Linux 或 macOS 上构建。

准备工作

  1. 安装并初始化 Google Cloud SDK

  2. 安装 Docker。最佳做法是使用与 Cloud Build 相同的 Docker 版本

  3. 您需要用于构建的源代码,构建的构建配置文件,以及从本地机器对构建步骤所需的任何工具和依赖项进行访问的权限。

  4. 如果您的构建需要访问私有注册表,请通过运行以下命令安装并配置 Cloud Build 的 Docker 凭据帮助程序

    gcloud components install docker-credential-gcr
    gcloud auth configure-docker
    

安装本地构建器

本地构建器是 Google Cloud SDK 的 gcloud 工具的一个组件。根据您所使用的系统,您可以通过 gcloud 命令、apt-getyum 安装本地构建器。

要安装本地构建器,请运行以下命令:

gcloud

gcloud components install cloud-build-local

apt-get

sudo apt-get install google-cloud-sdk-cloud-build-local

yum

sudo yum install google-cloud-sdk-cloud-build-local

安装本地构建器后,要查看:

  • 命令行帮助,请运行以下命令:

    cloud-build-local --help
    
  • 安装的本地构建器版本,请运行以下命令:

    cloud-build-local --version
    

在本地构建

警告:请在本地计算机上每次一个地运行构建。并行运行多个构建将导致本地构建器发生故障。

如果您尚未设置项目,可以使用快速入门中的配置测试本地构建器。

要在本地构建,请运行以下命令:

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --push [SOURCE_CODE]

其中:

  • [BUILD_CONFIG]配置文件的路径和名称。
    • 例如,如果您的配置文件位于工作目录中并且命名为 cloudbuild.json,则使用 --config=cloudbuild.json 标志。
    • 默认值为 cloudbuild.yaml,因此如果您的配置文件位于工作目录中并且命名为 cloudbuild.yaml,则无需添加此标志。
  • [SOURCE_CODE] 是源代码的路径。
    • 与 Cloud Build 一样,如果源代码位于您的当前工作目录中,则可以将 . 用于源。
    • 如果您的编译不需要源代码,请使用 --no-source 标志代替 [SOURCE_CODE]
  • --dryrun=false 允许构建运行。--dryrun 标志默认为 true。使用默认值运行会 lint 配置文件,但不会运行构建命令。您需要明确设置 --dryrun=false 才能执行构建。
  • --push 会将生成的映像或工件推送到由配置文件中的 imagesartifacts 字段定义的目标位置。默认情况下,系统会构建映像和工件,但不会将其推送到目标位置。

构建完成后,可通过 Docker 在本地机器上使用创建的映像。如果您向构建命令添加了 --push,这些映像将在指定的代码库中提供。

保留中间工件

构建期间,中间工件置于名为 workspace 的目录中。默认情况下,构建器会在构建结束时删除工作区及其内容。

要运行构建并保留工作区中的软件工件,请运行以下命令:

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --write-workspace=[LOCAL_DIRECTORY_PATH] [SOURCE_CODE]

其中:

  • [BUILD_CONFIG] 是配置文件的路径,
  • [SOURCE_CODE] 是源代码的路径,
  • [LOCAL_DIRECTORY_PATH] 是您希望在本地机器上存储工作区的本地目录。此目录不得位于 [SOURCE_CODE] 目录中

借助保留工作区功能,您可以:

  • 在调试构建时分析中间工件。
  • 访问构建器在工作区中创建的构建结果(例如二进制文件)。

在构建中使用替代变量

要在构建中使用替代变量,请将 --substitutions 标志与您要替换的 key=value 对一起使用。请注意,您可以为某些默认变量和已定义的变量指定值。

例如:

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --substitutions _KEY=value,_FOO=foo [SOURCE_CODE]

其中:

  • [BUILD_CONFIG] 是配置文件的路径,
  • [SOURCE_CODE] 是源代码的路径,
  • 在本示例中,_KEY 将替换为 value_FOO 将替换为 foo

如需详细了解包括所需语法在内的替代变量,请参阅替代变量

在本地调试构建

要调试构建,您可以:

  • 通过执行构建试运行来验证配置文件是否正确。
  • 检查构建期间在工作区中创建的中间工件。为此,请参阅上面的保留中间工件

本地构建使用执行时可用的权限在本地主机上运行。在 Cloud Build 中,构建步骤使用项目服务帐号的权限执行。如果要调试权限问题,请务必将权限设置为与 Cloud Build 服务帐号的权限相匹配,以使本地构建所处的环境与 Cloud Build 环境尽可能接近。

通过试运行验证构建

构建的试运行将 lint 配置文件,并且会在检测到任何问题时生成错误。试运行不执行构建,因此您可以验证配置文件,期间不会产生运行构建的开销。使用本地构建器是执行构建试运行的唯一方法。

  1. 使用以下命令执行构建试运行:

    cloud-build-local --config=[BUILD_CONFIG] [SOURCE_CODE]
    

    其中:

    • [BUILD_CONFIG] 是配置文件的路径,
    • [SOURCE_CODE] 是源代码的路径。
  2. 查看任何错误消息并修复配置文件中的任何问题。

限制和局限

  • 本地构建器只能在 Linux 或 macOS 上构建。
  • 在给定主机上,本地构建器每次运行一个构建。并行运行多个构建将导致本地构建器发生故障。
  • 本地构建器不支持与托管的 Cloud Build 服务 100% 的功能对等。本地构建器不支持的功能示例包括但不限于以下内容:
    • 动态替换
    • 专用池

本地构建器与 Cloud Build 之间的差异

本地构建器的设计初衷是模拟 Cloud Build,但它不能完全互操作。在本地构建器上成功运行的构建应以类似的行为在 Cloud Build 上运行,但不能保证在任何方向都兼容,并且 Cloud Build 中提供了在本地构建器中尚未实现的功能。

两个构建器之间的环境差异包括:

  • 本地构建器在本地机器上执行,Cloud Build 在 Google Cloud Platform 上执行。
  • 本地构建器使用您的个人帐号运行构建,Cloud Build 则使用 cloudbuild 服务帐号 [PROJECT_ID]@cloudbuild.gserviceaccount.com 运行构建。如果您在个人帐号上设置了任何适用于本地构建器的权限,则可能需要在 cloudbuild 服务帐号上复制这些权限。如需了解详情,请参阅设置服务帐号权限
  • 构建器使用的 Docker 版本可能不同。执行期间,只要安装的 Docker 版本与 Cloud Build 中使用的版本不同,本地构建器就会显示一条警告。最佳做法是使用与 Cloud Build 所用 Docker 版本相同的版本。

后续步骤