准备环境

在创建 Image Builder 流水线之前，您必须先准备 Google Cloud 环境。如需准备环境，请完成以下任务：

准备工作

  • 如果您尚未设置身份验证，请进行设置。身份验证用于验证您的身份，以便访问 Google Cloud 服务和 API。如需从本地开发环境运行代码或示例，您可以通过选择以下选项之一��� Compute Engine 进行身份验证：

    选择标签页以了解您打算如何使用本页面上的示例：

    控制台

    当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时，无需设置身份验证。

    gcloud

    1. 安装 Google Cloud CLI，然后 使用联合身份登录 gcloud CLI。 登录后，运行以下命令来初始化 Google Cloud CLI： 

      gcloud init
  • 设置默认区域和可用区。

    • REST

    如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。

      安装 Google Cloud CLI，然后 使用联合身份登录 gcloud CLI。

    如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

所需的角色

如需获得准备环境所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

  • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
  • 项目 Identity and Access Management (IAM) 管理员 (roles/resourcemanager.projectIamAdmin) 或服务账号管理员 (roles/iam.serviceAccountAdmin)
  • Artifact Registry Administrator (roles/artifactregistry.admin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

新手入门请求

Image Builder 已正式推出，但仅面向列入许可名单的客户提供。如需为您的 Google Cloud 项目启用映像自定义流水线，请提交访问权限申请表单或与您的 Google Cloud 客户支持团队联系。

已列入许可名单的服务账号

许可名单会按项目编号授予对项目的访问权限。因此，许可名单仅涵盖以下服务账号：

  • 您在项目中创建的用户代管式服务。
  • Google Cloud 在您的项目中创建的默认服务账号，例如 Compute Engine 默认服务账号 (PROJECT_NUMBER-compute@)。

许可名单不涵盖 Google 拥有的服务账号，因为Google Cloud 会在 Google 拥有的项目（而不是您的项目）中创建这些服务账号。Google 拥有的服务账号包括以下账号：

  • 服务代理，例如 service-PROJECT_NUMBER@gcp-sa-SERVICE.。
  • 旧版 Cloud Build 服务账号 (PROJECT_NUMBER@cloudbuild.)，由 Google 拥有和管理。

如需详细了解这些服务账号类型，请参阅服务账号类型。

如果构建以 Google 拥有的服务账号身份运行，则该构建无法读取 Artifact Registry 中的 Image Builder 编排器容器映像。因此，流水线会因权限遭拒错误而失败。为避免此失败，请以您在项目中创建的用户代管式服务账号运行流水线，并在提交 build 时指定该服务账号。如需了解详情，请参阅配置 Image Builder 服务账号和默认 Cloud Build 服务账号。

启用 API

Image Builder 要求您启用 Compute Engine、Cloud Build、Artifact Registry、Service Usage 和 Resource Manager API。如需使用 Google Cloud 控制台或 Google Cloud CLI 启用 API，请选择以下任一标签页：

控制台

启用 Compute Engine API、Cloud Build API、Artifact Registry API、Service Usage API 和 Cloud Resource Manager API（如果尚未启用）。

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。 了解如何授予角色。

启用 API

gcloud

启用 Compute Engine API、Cloud Build API、Artifact Registry API、Service Usage API 和 Cloud Resource Manager API（如果尚未启用）：

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。 

gcloud services enable compute.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com serviceusage.googleapis.com cloudresourcemanager.googleapis.com

配置 Image Builder 服务账号

Image Builder 编排程序使用用户代管式服务账号运行。运行映像构建流水线时，Cloud Build 会将此服务账号附加到临时工作器虚拟机和测试虚拟机实例，以执行自定义和验证操作。此服务账号需要具有以下角色：

  • Compute Admin (roles/compute.admin)：管理虚拟机实例、永久性磁盘和客机操作系统映像。
  • Service Account User (roles/iam.serviceAccountUser)：允许 Cloud Build 将服务账号附加到临时工作器和测试虚拟机实例。
  • Storage Admin (roles/storage.admin)：在 Cloud Storage workdir 暂存存储桶中读取和写入临时 build 工件和日志。
  • Logging Log Writer (roles/logging.logWriter)：将执行日志写入 Cloud Logging。
  • Service Usage Viewer (roles/serviceusage.serviceUsageViewer)：在流水线执行期间检查项目服务状态。
  • Cloud Build Editor (roles/cloudbuild.builds.editor)：触发并运行 Cloud Build 作业，以及导出映像。
  • （可选）Artifact Registry Admin (roles/artifactregistry.admin)：将生成的操作系统映像 tar 文件上传到 Artifact Registry。

您可以使用现有服务账号，也可以为 build 流水线创建新的专用服务账号。使用位于您项目中的服务账号。请勿以 Google 拥有的服务账号（例如旧版 Cloud Build 服务账号）的身份运行流水线，因为 Image Builder 许可名单不包含这些服务账号。如需了解详情，请参阅列入许可名单的服务账号和默认 Cloud Build 服务账号。

如需创建新的专用服务账号并使用 Google Cloud 控制台或 gcloud CLI 授予所需角色，请选择以下标签页之一：

控制台

    确保您拥有 Create Service Accounts IAM 角色 (roles/iam.serviceAccountCreator) 和 Project IAM Admin 角色 (roles/resourcemanager.projectIamAdmin)。了解如何授予角色。

  1. 在 Google Cloud 控制台中，前往创建服务账号页面。

    转到“创建服务账号”
  2. 选择您的项目。

  3. 在服务账号名称字段中，输入一个名称。 Google Cloud 控制台会根据此名称填充服务账号 ID 字段。

    在服务账号说明字段中，输入说明。例如，Service account for quickstart。

  4. 点击创建并继续。

  5. 向服务账号授予以下角色：Compute Engine > Compute Admin、Service Accounts > Service Account User、Cloud Storage > Storage Admin、Cloud Logging > Logs Writer、Service Usage > Service Usage Viewer、Cloud Build > Cloud Build Editor、Artifact Registry > Artifact Registry Admin。

    如需授予角色，请找到选择角色列表，然后选择相应角色。

    如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。

  6. 点击继续。

  7. 在服务账号用户角色字段中，输入将服务账号关联到其他资源（例如 Compute Engine 实例）的主账号的标识符。

    这通常是员工身份池中的用户的标识符。如需了解详情，请参阅 在 IAM 政策中表示员工池用户。

  8. 点击完成以完成服务账号的创建过程。

gcloud

  1. 为您的 build 流水线创建服务账号：

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --display-name="Image Builder Service Account"

  2. 向您的服务账号授予所需的角色（roles/compute.admin、roles/iam.serviceAccountUser、roles/storage.admin、roles/logging.logWriter、roles/serviceusage.serviceUsageViewer 和 roles/cloudbuild.builds.editor）：

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/compute.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/logging.logWriter"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/serviceusage.serviceUsageViewer"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/cloudbuild.builds.editor"

  3. 可选：向您的服务账号授予可选角色 (roles/artifactregistry.admin)：

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/artifactregistry.admin"

替换以下内容：

  • SERVICE_ACCOUNT_NAME：要创建的 build 服务账号的名称。例如 custom-builder-sa。
  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • SERVICE_ACCOUNT_EMAIL：您的 build 服务账号的电子邮件地址。

配置可信映像组织政策

由于 Image Builder 在构建执行期间会在内���使用标准的 Compute Engine 映像导入和导出工具，因此您项目的可信映像政策 (compute.trustedImageProjects) 必须明确允许来自以下项目的映像：

  • projects/compute-image-import

如果您的组织政策限制了此项目，映像导出阶段将失败。

如需更新组织政策，请执行以下操作：

  1. 在组织政策中，针对 compute.trustedImageProjects 限制，将 projects/compute-image-import 添加到允许的发布商列表中。
  2. 如需详细了解如何配置组织政策限制条件，请参阅设置可信映像政策和将自定义映像导出到 Cloud Storage。

配置 VPC 网络和访问权限要求

在 build 和验证阶段，Image Builder 会在您的 Google Cloud 项目中预配临时工作器和测试虚拟机。默认情况下，Image Builder 会将实例连接到您的 default VPC 网络，并分配临时外部 IP 地址。

如果您在 imagebuilder.yaml 配方文件中指定了自定义 network 或 subnetwork，或者配置了 externalIP: none，则：

  • 专用 Google 访问通道和 Cloud NAT：如果工作器或测试虚拟机配置为 externalIP: none（没有外部 IP），则您的 VPC 子网必须启用专用 Google 访问通道，以便实例可以访问 Google API 和服务（例如 Cloud Storage 和 Artifact Registry）。如果您的自定义步骤从外部互联网代码库下载操作系统软件包或依赖项，您还必须在子网上配置 Cloud NAT。
  • 防火墙规则：确保您的 VPC 防火墙规则允许出站流量流向 Google API 和必要的软件代码库。如果您计划连接到活跃的工作器虚拟机以进行交互式调试 (debug: true)，请确保防火墙规则允许在 TCP 端口 22 上入站。如果虚拟机实例没有外部 IP 地址，请允许来自 Identity-Aware Proxy (IAP) IP 地址范围 35.235.240.0/20 的入站流量，以进行 TCP 转发。

配置 Artifact Registry

如需存储和管理自定义操作系统映像、安全元数据和 SLSA 构建出处证明，您必须在 Artifact Registry 中设置一个通用仓库。将映像存储在 Artifact Registry 中，可让您维护已发布映像的安全且不可变的记录。

配置 Artifact Registry 目标位置后，Image Builder 会执行以下步骤：

  • 将最终的虚拟机启动磁盘导出为标准 tar 文件 (.tar.gz)。
  • 将 tar 文件上传到 Artifact Registry 中的通用代码库。
  • 为制品生成并签署 SLSA build 出处证明，以将其与来源元数据相关联。
  • 使用 Artifact Registry tar 文件 URI 作为模板源，向 Compute Engine 注册可用于生产用途的 Compute Engine 映像。

如需配置通用 Artifact Registry，请完成以下任务：

  1. 确保用于运行 Image Builder 流水的服务账号在代码库或项目级层具有 Artifact Registry Admin 角色 (roles/artifactregistry.admin)。如需详细说明，请参阅配置 Image Builder 服务账号。

  2. 创建格式为 generic 的代码库。如需创建代码库，请运行 gcloud artifacts repositories create 命令：

    gcloud artifacts repositories create REPOSITORY_NAME \
    --repository-format=generic \
    --location=REPOSITORY_LOCATION

    替换以下占位符：

    • REPOSITORY_NAME：通用代码库的名称。例如 custom-os-images。
    • REPOSITORY_LOCATION：受支持的区域。例如 us-central1。

后续步骤