支持的自定义操作

如需自定义虚拟机映像（例如运行终端脚本、更新启动参数、转移二进制文件或安装 GPU 驱动程序），您可以在自定义配方 (imagebuilder.yaml) 的 spec.steps 块内定义特定的辅助操作。

概览

在 Image Builder 构建的执行阶段，编排器会在临时工作器虚拟机上按顺序运行自定义配方 (spec.steps) 中声明的步骤。

每个步骤都必须指定一个 name、一个 action 和一个针对相应操作类型量身定制的 inputs 块。Image Builder 支持以下自定义操作：

• Shell：在工作器客户机操作系统上执行内嵌终端脚本或命令。
• UpdateKernelCommandLine：修改启动参数和内核命令行标志。
• FileCopy：将配置文件、脚本或资源从 Cloud Storage 或本地工作区转移到虚拟机。
• InstallGPU：下载、编译和注册 NVIDIA GPU 驱动程序。

Shell 操作

借助 Shell 操作，您可以在临时工作器虚拟机的 guest 操作系统上执行内嵌终端脚本或单个 shell 命令，以执行自定义操作，例如更新软件包、配置用户账号或编译软件。

在 steps.inputs 下指定以下任一输入内容：

• inlineScript（字符串）：要执行的原始多行 shell 命令。
• command（字符串）：单个系统命令字符串或二进制文件可执行文件的相对路径。

示例配置

以下标签页显示了运行内嵌脚本与运行单个命令的示例步骤配置：

- name: "Update guest packages and configure groups"
  action: Shell
  inputs:
    inlineScript: |
      #!/bin/bash
      apt-get update -y
      apt-get install -y fail2ban build-essential
      groupadd -r adminusers

- name: "Log kernel identifier"
  action: Shell
  inputs:
    command: "uname -a"

特殊行为

当您运行 Shell 操作时，自定义配置程序会管理安全性审核和自动系统重启，如下几部分中所述：

安全审核

为防止敏感令牌、密钥或专有代码泄露到执行日志中，自定义配置器不会打印脚本的原始行，除非启用了交互式调试 (debug: true)。否则，它会将脚本载荷的 SHA-256 完整性哈希记录到 build 日志中。此哈希可提供有关映像上运行的代码的不可变审核跟踪记录。

系统重新启动（退出代码 3010）

某些 shell 操作（例如内核补丁更新或存储分区调整）需要重新启动系统，然后才能运行后续步骤。

如需在自定义期间请求系统重新启动，您的 shell 脚本必须以命令 exit 3010 结束。当自定义预配工具收到退出代码 3010 时，它会按如下方式处理重启生命周期：

1. 预配工具检测到退出代码 3010，暂停执行，并标记步骤进度索引。
2. 预配工具会重新启动工作器虚拟机。
3. 虚拟机重启后，配置器会装载工作区，并自动恢复队列中的流水线，从下一步开始执行。

重新启动示例：

以下示例展示了一个更新软件包并请求重新启动的步骤配置：

- name: "Install core updates and request reboot"
  action: Shell
  inputs:
    inlineScript: |
      #!/bin/bash
      echo "Applying configuration package upgrades..."
      apt-get dist-upgrade -y
      # Terminate with return code 3010 to trigger a system reboot
      exit 3010
- name: "Post-reboot verification"
  action: Shell
  inputs:
    command: "uname -r"

UpdateKernelCommandLine 操作

UpdateKernelCommandLine 操作用于查找、替换、插入或移除在系统启动时传递给内核的命令行标志，例如在配置控制台日志或调整内核参数时。

在 steps.inputs 映射下指定以下属性：

• oldArguments（字符串，必需）：要在引导加载程序配置中查找、移除或替换的确切命令行实参。
• newArguments（字符串，可选）：要写入以取代目标标志的替换实参。如果您省略 newArguments 属性，Image Builder 会从引导行中完全移除 oldArguments 属性中配置的参数。

示例配置

以下标签页显示了用于替换或移除内核启动实参的示例步骤配置：

- name: "Configure detailed boot logging"
  action: UpdateKernelCommandLine
  inputs:
    oldArguments: "loglevel=4"
    newArguments: "loglevel=6 console=ttyS0"

- name: "Enable verbose startup diagnostics"
  action: UpdateKernelCommandLine
  inputs:
    oldArguments: "quiet"

特定于操作系统的执行详细信息

以下标签页介绍了自定义配置器如何根据源 guest 操作系统处理映像修改：

FileCopy 操作

FileCopy 操作会将配置文件、二进制文件或证书从远程存储桶或本地代码库复制到自定义映像。自定义预配工具会下载或读取源文件，将其写入工作器虚拟机上指定的 guest 路径，并配置权限。

在 steps.inputs 下指定以下输入：

• destination（字符串，必需）：客户机操作系统中创建文件的绝对路径。
• permissions（字符串，必需）：目标配置权限的八进制表示形式，例如 "0755" 或 "0644"。
• 指定以下任一来源属性：
  • gcsSourcePath（字符串）：源文件的 Cloud Storage URI，必须采用 gs://BUCKET_NAME/OBJECT_NAME 格式。
  • localSourcePath（字符串）：本地工作区代码库文件夹中文件的相对路径。出于安全考虑，系统已屏蔽使用 ../ 的路径遍历。

示例配置

以下标签页显示了从 Cloud Storage 复制文件与从本地工作区复制文件的示例步骤配置：

- name: "Import licensing configuration"
  action: FileCopy
  inputs:
    gcsSourcePath: "gs://enterprise-configs-bucket/licensing/license.key"
    destination: "/etc/app/license.key"
    permissions: "0600"

- name: "Deploy setup automation daemon"
  action: FileCopy
  inputs:
    localSourcePath: "bin/setup-daemon"
    destination: "/usr/local/bin/setup-daemon"
    permissions: "0755"

特定于操作系统的准则

以下标签页介绍了文件位置指南，具体取决于目标 guest 操作系统：

InstallGPU 操作

使用 InstallGPU 操作可构建针对机器学习、数据科学或科学工作负载进行了优化的虚拟机映像。Image Builder 会在自定义映像上下载、编译和注册 NVIDIA GPU 驱动程序。您可以根据基本映像类型和目标硬件，选择安装预编译的驱动程序或编译自定义驱动程序 .run 文件。

在 steps.inputs 下指定以下输入之一：

• version（字符串）：目标 NVIDIA 驱动程序版本号，例如 "595.129.03"。如果您仅指定 version，编排器会从官方 NVIDIA 库 (https://us.download.nvidia.com/tesla/<version>) 下载驱动程序。
• gcsRunfile（字符串）：自定义 NVIDIA 驱动程序安装程序文件的 Cloud Storage 路径，必须采用 gs://BUCKET_NAME/OBJECT_NAME.run 格式。
• sourceRunfile（字符串）：本地工作区代码库文件夹内安装程序 .run 文件的相对路径。

示例配置

以下标签页显示了安装特定预打包驱动程序版本与安装自定义运行文件的示例步骤配置：

- name: "Configure default NVIDIA drivers"
  action: InstallGPU
  inputs:
    version: "<var>DRIVER_VERSION</var>"

- name: "Deploy custom GPU driver from Cloud Storage"
  action: InstallGPU
  inputs:
    gcsRunfile: "gs://<var>BUCKET_NAME</var>/drivers/NVIDIA-Linux-aarch64-<var>DRIVER_VERSION</var>.run"

- name: "Deploy custom GPU driver from workspace"
  action: InstallGPU
  inputs:
    sourceRunfile: "drivers/NVIDIA-Linux-x86_64-<var>DRIVER_VERSION</var>.run"

配置方法

以下标签页介绍了在自定义映像上配置 NVIDIA GPU 驱动程序的受支持方法：

后续步骤

• 查看映像自定义文件架构中的顶级架构块。
• 在 Cloud Build 配置文件架构中配置流水线编排参数。
• 按照教程创建 Image Builder 流水线操作。