cloud-build-basics

Cloud Build 基础知识

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，你必须阅读使用归属信息。对于直接在终端中执行的命令（绝不可用于生成的脚本、Terraform 或用户代码），请在 gcloud 前添加前缀 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-build-basics)" ，并将 agent-skills/1.0 (skill:cloud-build-basics) 添加到 User-Agent 标头中。

前置条件

开始之前，请确保满足以下前置条件：

1. Google Cloud SDK：确保已安装并配置 Google Cloud SDK。
2. 身份验证：对 gcloud CLI 进行身份验证：

   gcloud auth login
   gcloud auth application-default login
   

3. 项目 ID：了解目标 Google Cloud 项目 ID。设置上下文：

   gcloud config set project <PROJECT_ID>
   

4. 启用 Cloud Build API：必须为项目启用 Cloud Build API。

   gcloud services enable cloudbuild.googleapis.com
   

5. 权限：确保用户或服务账号拥有所需权限，例如 roles/cloudbuild.builds.editor 和 roles/serviceusage.serviceUsageAdmin（用于启用 API）。

核心概念

Cloud Build（GCB）是一个无服务器平台，可在 Google Cloud 上执行构建。它会将源代码转换为可部署的工件，例如 Docker 容器或 Java 归档文件。

概念	说明
cloudbuild.yaml	定义构建步骤的必需配置文件，采用 YAML 或 JSON 编写。
构建步骤	GCB 执行的一系列操作（步骤）。每个步骤都会在特定的 Docker 容器（构建器）中运行命令。常见的构建器包括 gcr.io/cloud-builders/gcloud、gcr.io/cloud-builders/docker 和自定义容器。
工件	构建的输出，通常是推送到 Google Container Registry（GCR）或 Artifact Registry（AR）的容器映像，也可以是其他可部署文件。
触发器	自动化规则，可在事件发生时启动构建，例如向 Git 仓库推送代码、收到 Pub/Sub 消息或收到手动请求。

导航：查看构建历史记录

Cloud Build 构建历史记录页面是监控过去及正在进行的构建状态的中心位置。

1. 打开 Cloud Console：前往 Google Cloud Console。
2. 前往 Cloud Build：使用搜索栏或导航菜单查找 Cloud Build。
3. 选择构建历史记录：在左侧导航窗格中选择 History（或使用直接网址：https://console.cloud.google.com/cloud-build/builds）。
4. 查看构建：
   • 状态：查看状态列（SUCCESS、FAILURE、WORKING、QUEUED）。
   • 区域：使用顶部的区域筛选条件，查看在特定区域运行的构建（这对于区域级工作池很重要）。
   • 日志：点击特定的构建 ID，查看详细日志、执行步骤和构建摘要。调试失败的构建时，这些信息至关重要。

说明

如果你是首次访问此页面，可能会看到“初始状态”体验，其中提供了运行示例构建或创建首个触发器的选项（如 cb-list-build-zero-state 技能中所述）。请注意，触发器和构建的区域设置在创建后不可更改，因此必须谨慎选择。

创建基本的自动化触发器

此流程用于定义一条自动化规则：每当代码推送到指定的 Git 分支时，就运行一次构建。

第 1 步：开始创建触发器

1. 前往 Cloud Build Triggers 页面（https://console.cloud.google.com/cloud-build/triggers）。
2. 点击 Create trigger。

第 2 步：配置触发器设置

1. 名称：提供一个唯一且描述性明确的名称（例如，github-main-branch-build）。
2. 区域：选择存储触发器配置的区域（例如，global 或特定区域端点）。注意：触发器和构建区域设置在创建后不可更改，必须谨慎选择。
3. 事件：选择事件类型。对于自动化 CI/CD，请选择 推送到分支。
4. 来源：选择代码库来源：
   • 代码库：连接源代码库（GitHub、Bitbucket、Cloud Source Repositories 等）。如有需要，请授权连接。
   • 代码库名称：选择要关联的特定代码库。
5. 分支：输入分支模式（例如，^main$ 或 ^develop）。

第 3 步：配置构建设置

1. 配置：选择 Cloud Build 配置文件（yaml 或 json）。
2. 位置：保留默认的 代码库，并指定构建配置文件的路径（例如，cloudbuild.yaml）。
   • 替代方案：对于非常简单的构建，可以选择 内联，直接将 YAML 配置粘贴到触发器中。
3. （可选）服务账号：对于生产环境，请选择权限受限的专用服务账号，以遵循最小权限原则。

第 4 步：保存并测试

1. 点击 创建。触发器现已启用，会在下次匹配的 Git 推送时自动运行。

提示

cb-create-trigger 技能提供详细的 gcloud 命令，可用于创建各种类型的触发器（GitHub、Pub/Sub、Webhook）和配置（内联、Dockerfile、YAML）。使用该技能进行 CLI 自动化。

手动运行现有触发器

有时，你需要按需运行触发器，而不是遵循其正常的自动化流程（例如，重新构建旧提交或测试新的替换项）。

重要

替换项不可变：你只能覆盖触发器配置中已定义的替换变量的值。运行时无法引入新的替换变量键。

选项 A：通过 Cloud Console

1. 前往 Cloud Build 触发器页面（https://console.cloud.google.com/cloud-build/triggers）。
2. 找到要运行的触发器。
3. 点击触发器旁边的垂直省略号（⋮），然后选择 运行。
4. 系统会显示一个对话框，你可以在其中指定：
   • 源分支/标记：选择要用于构建的特定 Git 引用。
   • 替换变量：覆盖任何现有替换变量（例如，将 _VERSION 设置为新值）。
5. 点击 运行触发器。构建会立即开始，你可以在 历史记录页面上查看其状态。

选项 B：通过 gcloud CLI

使用 gcloud builds triggers run 命令调用触发器，并可选择覆盖参数。

# Run the trigger against the 'main' branch
gcloud builds triggers run <TRIGGER_NAME> \
    --region=<REGION> \
    --branch=main

# Run the trigger and override a substitution variable
gcloud builds triggers run <TRIGGER_NAME> \
    --region=<REGION> \
    --branch=main \
    --substitutions=_IMAGE_TAG="20231027-manual"

# Monitor the initiated build
# Note: The run command outputs the build ID. Use it to check status:
# gcloud builds log <BUILD_ID> --region=<REGION>

说明

cb-run-trigger 技能提供更复杂的调用示例，包括针对特定提交 SHA 运行或使用标记运行。

相关技能

• cb-create-trigger：创建所有触发器类型的详细 CLI 操作说明。
• cb-list-build-zero-state：Cloud Build 信息中心和入门空状态的高级管理。
• cb-run-trigger：使用各种 gcloud 选项手动运行触发器的综合指南。

外部资源和文档

• Cloud Build 文档
• Cloud Build 配置文件架构
• 使用触发器自动化构建
• gcloud CLI builds 参考