排查流水线失败问题

如果 Image Builder 流水线在自定义阶段失败，请查看日志文件、在工作器虚拟机上配置交互式调试标志，或分析中间调试映像，以找出编译时错误或脚本错误。

准备工作

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

    1. 安装 Google Cloud CLI。 安装完成后，运行以下命令来初始化 Google Cloud CLI： 

      gcloud init

      如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

    2. 设置默认区域和可用区。

查看日志记录渠道

Image Builder 会将日志写入多个位置，以帮助您诊断堆栈不同级别上的故障：

  • Cloud Build 编排器日志：在 Cloud Build 控制台中显示高级构建器步骤。如果某个步骤失败，系统会打印指向相应 Cloud Storage 工作目录的链接。
  • 自定义虚拟机代理日志：自定义代理会捕获自定义步骤的标准输出 (stdout) 和标准错误 (stderr)。编排程序会轮询这些记录，并将其直接流式传输到 Cloud Build 跟踪日志中。如果日志被截断，或者您需要检查完整日志，请前往 _GCS_WORKDIR 存储桶中与您的 build ID 匹配的文件夹。
  • 串行控制台日志：如果客机操作系统无法启动，自定义代理将无法启动。在这种情况下，请查看串行控制台日志。编排器会将工作器虚拟机的串行端口输出直接流式传输到您的 Cloud Storage 工作目录存储桶。在失败的 Cloud Build 轨迹末尾，系统会打印一个指向串行日志文件的链接。
  • 客户机操作系统日志：为了在 Linux 上进行详细的系统级问题排查，自定义代理会在运行结束时将完整的系统 journal 日志副本上传到您的 Cloud Storage 工作目录存储桶。

使用调试标志解决脚本失败问题

默认情况下，如果自定义步骤失败，Image Builder 会立即终止执行并删除工作器虚拟机，以控制费用。

如需以交互方式调试脚本，您可以启用 debug 标志。这样可使虚拟机保持活跃状态，从而让您能够使用 SSH 直接连接到活跃的客户操作系统。

启用调试标志

在 imagebuilder.yaml 文件中，在 infrastructureConfig 代码块下设置 debug: true：

infrastructureConfig:
  machineType: e2-standard-4
  zone: us-central1-a
  # Enable interactive debugging
  debug: true
  instanceDurationHours: 1.5

触发 build 并等待失败

使用标准方法提交 build。如果流水线遇到脚本错误，则会发生以下情况：

  1. 编排器会暂停 build 执行。
  2. Image Builder 不会删除工作器虚拟机。它会继续在您的项目中运行。
  3. 虚拟机在自动终止之前会保持活动状态，时长为 instanceDurationHours 属性中指定的时间。

连接到工作器虚拟机以进行调试

查看 Cloud Build 控制台输出，以检索有效工作器虚拟机实例的名称。打开终端并使用 gcloud compute ssh 连接到工作器虚拟机：

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID

如果您的 imagebuilder.yaml 文件配置了 externalIP: none，导致没有外部 IP 地址，请添加 --tunnel-through-iap 标志以使用 Identity-Aware Proxy (IAP) TCP 转发进行连接：

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID \
    --tunnel-through-iap

连接后，您可以实时运行命令、检查目标文件、分析正在运行的进程、查看安装程序历史记录日志，以及直接在磁盘上测试脚本修改。

分析中间调试映像

除了使用 debug 标志保持工作器虚拟机的活跃状态之外，您还可以使用自动生成的调试映像来分析磁盘状态：

  1. 如果 build 因 debug: false（默认）而失败，编排器会将部分自定义的启动磁盘导出为 Compute Engine 映像。
  2. 调试映像使用 image-builder-debug-image-BUILD_ID 模式命名，并分配给 image-builder-debug-images 映像系列。

  3. 如需检查文件系统，请使用此调试映像作为启动磁盘创建临时虚拟机实例：

    gcloud compute instances create temp-debug-vm \
    --image-family=image-builder-debug-images \
    --zone=ZONE \
    --project=PROJECT_ID

  4. 连接到 temp-debug-vm 实例，检查磁盘并找出自定义失败的原因。

解决 Cloud Build 超时问题

如果 Image Builder 流水线运行时间超出预期，Cloud Build 作业会停止并失败，状态为 TIMEOUT。

构建时间可能会有所不同，通常对于资源规模更大的机器类型，构建时间会更长，因此请设置超时时间，以便为构建完成留出更多时间。如果未设置，则默认 Cloud Build 超时时间为 1 小时 (3600s)。

如需配置更长的超时时间，请在 cloudbuild.yaml 文件的根级设置 timeout 字段：

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

# Increase the overall build timeout (for example, 2 hours)
timeout: '7200s'

更新超时值后，重新运行 build 并验证 Image Builder 流水线是否能够执行完成。

如需详细了解 timeout 参数，请参阅 Cloud Build 文档中的 timeout。