图片自定义文件

本文档介绍了自定义配方文件 imagebuilder.yaml 的结构和参数，您可以使用该文件为 Image Builder 流水线定义基本操作系统映像、硬件配置、发布目标和自定义操作。

架构概览

自定义配置使用 API 版本 imagebuilder.gcp.com/v1 和资源种类 OSImageCustomization。

标准配方文件的结构如下：

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
infrastructureConfig:
  # VM machine type, zone, and network settings
source:
  # Base source image profile
destinations:
  # Output OS image release targets
spec:
  config:
    # Build options and validation test flags
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)

元数据

提供此自定义 build 模板的标识详细信息：

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name（字符串，必需）：相应配置的标识符。
  • description（字符串，可选）：相应 build 的用途说明。

基础设施配置

指定 Image Builder 在构建和验证任务期间创建的临时虚拟机实例的硬件和网络属性：

infrastructureConfig:
  machineType: MACHINE_TYPE
  zone: ZONE
  network: projects/PROJECT_ID/global/networks/NETWORK_NAME
  subnetwork: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
  externalIP: ephemeral
  acceleratorType: nvidia-l4
  acceleratorCount: 1
  debug: false
  instanceDurationHours: 2.0
  reservations:
    - RESERVATION_NAME
  • machineType（字符串，必需）：要用于工作器和测试虚拟机的 Compute Engine 机器类型。确保机器类型与您在 imageFamily 或 imagePath 中指定的源映像的架构相匹配。例如，为 x86 映像使用 e2-standard-4，为 Arm 映像使用 c4a-standard-4。不支持裸机机器类型。
  • zone（字符串，必需）：运行工作器和测试虚拟机的可用区，例如 us-central1-a。
  • network（字符串，可选）：要附加到工作器和验证测试虚拟机的 VPC 网络，例如 projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> 或 default。如果省略，映像构建器会使用默认网络。
  • subnetwork（字符串，可选）：要附加到工作器和验证测试虚拟机的 VPC 子网，例如 projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>。
  • externalIP（字符串，可选）：指定工作器和验证测试虚拟机的外部 IP 地址分配。允许的值：
    • ephemeral（默认）：从共享池分配公共临时 IPv4 地址。
    • none：创建没有外部 IP 地址的虚拟机，仅使用专用 VPC 网络。如果设置为 none，请确保您的 VPC 子网已启用专用 Google 访问通道或 Cloud NAT，以便虚拟机可以访问所需的 Google Cloud 服务和软件包代码库。
  • acceleratorType（字符串，可选）：要挂接到工作器虚拟机的 GPU 加速器类型，例如 nvidia-tesla-t4 或 nvidia-l4。
  • acceleratorCount（数字，可选）：要附加到工作器虚拟机的 GPU 加速器数量。
  • debug（布尔值，可选）：如果您将 debug 设置为 true，无论自定义完成还是失败，Image Builder 都会保留工作器虚拟机，以便您可以使用 SSH 检查或排查活动实例的问题。默认值为 false。
  • instanceDurationHours（数字，可选）：限制工作器虚拟机的运行时。 时间限制从自定义完成或遇到脚本错误时开始，允许您在交互式调试会话期间连接到活跃的虚拟机。上限为 2.0 小时。
  • reservations（字符串数组，可选）：当 Image Builder 创建虚拟机时要使用的容量预留资源名称（例如同一项目中的 test-reservation）。

来源映像

用于标识 Image Builder 用于启动工作器虚拟机的基本操作系统映像。您必须指定以下选项之一：

如需指定标准映像系列，请执行以下操作：

source:
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY

如需指定直接映像版本 URI，请执行以下操作：

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily（字符串）：标准映像家人群组的路径，例如 projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts。
  • imagePath（字符串）：特定 Compute Engine 映像版本的直接资源 URI，例如 projects/cos-cloud/global/images/cos-105-17412-226-28。

目的地

定义了发布编译后的自定义操作系统映像的位置和方式。此属性包含 diskImage 下的发布目的地对象列表：

destinations:
  - diskImage:
      name: IMAGE_NAME
      project: PROJECT_ID
      family: IMAGE_FAMILY
      description: DESCRIPTION
      licenses:
        - projects/PROJECT_ID/global/licenses/LICENSE_NAME
      labels:
        env: production
      signatureDatabaseFile: SIGNATURE_DB_PATH
      storageLocations:
        - us-central1
  • name（字符串，必需）：分配给最终 Compute Engine 映像资源的基本名称前缀。Image Builder 会自动将唯一的 build ID 附加到此前缀，并将最终映像名称截断为 63 个字符。
  • family（字符串，可选）：要应用于新生成的映像的映像系列。
  • project（字符串，必需）：Image Builder 将输出映像写入到的 Google Cloud 项目。
  • description（字符串，可选）：附加到生成的图片元数据的说明文本。
  • licenses（字符串数组，可选）：应用于此映像的特定软件许可的资源路径。
  • labels（映射，可选）：标记元数据键值对，例如 env: production。
  • signatureDatabaseFile（字符串，可选）：指向安全启动签名数据库文件的资源路径。
  • storageLocations（字符串数组，可选）：目标存储区域或多区域，例如 us-central1 或 us，Compute Engine 在其中存储最终磁盘块。注意：虽然此属性的格式为列表，但您只能为每个图片目的地指定一个位置。

规范配置

应用常规执行选项：

spec:
  config:
    skipSystemTests: false
  • skipSystemTests（布尔值，可选）：切换测试虚拟机是否评估启动条件、网络和 UEFI 结构。默认值为 false。

指定步骤

指定 Image Builder 在工作器虚拟机上按顺序运行的步骤对象列表。如需查看每个步骤类型的完整输入参数架构和使用示例，请参阅支持的自定义操作。

所有自定义步骤对象都具有以下共同属性：

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name（字符串，必需）：此自定义步骤的用户定义名称。
  • action（字符串，必需）：要调用的辅助操作。支持的操作：
  • inputs（对象，必需）：所选操作所需的键值对属性。如需查看完整的参数参考文档和示例，请参阅支持的自定义操作。

以下代码段展示了使用 Shell 操作的示例步骤：

spec:
  steps:
    - name: setup-environment
      action: Shell
      inputs:
        inlineScript: |
          #!/usr/bin/env bash
          echo "Running customization..."

后续步骤