圖片自訂檔案

本文說明自訂配方檔案 imagebuilder.yaml 的結構和參數，您可以使用這個檔案定義 Image Builder 管道的基本 OS 映像檔、硬體設定、發布目的地和自訂動作。

結構定義總覽

自訂設定會使用 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)

中繼資料

提供這個自訂建構範本的識別詳細資料：

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (字串，必填)：這項設定的 ID。
  • description (字串，選用)：說明建構版本的用途。

基礎架構設定

指定 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 (字串，必填)：用於 worker 和測試 VM 的 Compute Engine 機型。請確認機型與您在 imageFamily 或 imagePath 中指定的來源映像檔架構相符。舉例來說，x86 映像檔使用 e2-standard-4，Arm 映像檔則使用 c4a-standard-4。不支援裸機機器類型。
  • zone (字串，必填)：執行工作者和測試 VM 的可用區，例如 us-central1-a。
  • network (字串，選用)：要附加至工作站和驗證測試 VM 的虛擬私有雲網路，例如 projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> 或 default。如果省略這個標記，Image Builder 會使用預設網路。
  • subnetwork (字串，選用)：要附加至工作站和驗證測試 VM 的虛擬私有雲子網路，例如 projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>。
  • externalIP (字串，選用)：指定工作站和驗證測試 VM 的外部 IP 位址分配。允許的值：
    • ephemeral (預設)：從共用集區分配公開臨時 IPv4 位址。
    • none：建立沒有外部 IP 位址的 VM，僅使用私有虛擬私有雲網路。如果設為 none，請確保虛擬私有雲子網路已啟用 Private Google Access 或 Cloud NAT，VM 才能存取必要的 Google Cloud 服務和套件存放區。
  • acceleratorType (字串，選用)：要附加至工作站 VM 的 GPU 加速器類型，例如 nvidia-tesla-t4 或 nvidia-l4。
  • acceleratorCount (數字，選用)：要連接至 worker VM 的 GPU 加速器數量。
  • debug (布林值，選用)：如果將 debug 設為 true，無論自訂作業完成或失敗，Image Builder 都會保留 worker VM，方便您使用 SSH 檢查或排解現用執行個體的疑難。預設為 false。
  • instanceDurationHours (數字，選用)：限制 worker VM 執行階段。自訂作業完成或發生指令碼錯誤時，時間限制就會開始計算，您可以在互動式偵錯工作階段期間連線至作用中的 VM。最多 2.0 小時。
  • reservations (字串陣列，選用)：容量預留資源名稱 (例如同一專案中的 test-reservation)，供 Image Builder 建立 VM 時使用。

來源映像檔

識別 Image Builder 用於啟動工作者 VM 的基礎作業系統映像檔。您必須指定下列其中一個選項：

如要指定標準映像檔系列：

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。

目的地

定義發布編譯完成的自訂 OS 映像檔的位置和方式。這個屬性包含 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 會自動在這個前置字元後面加上不重複的建構 ID，並將最終映像檔名稱截斷為 63 個字元。
  • family (字串，選用)：要套用至新生成圖片的映像檔系列。
  • project (字串，必填)： Google Cloud Image Builder 寫入輸出映像檔的專案。
  • description (字串，選用)：附加至生成圖片中繼資料的說明文字。
  • licenses (字串陣列，選用)：套用至這個映像檔的特定軟體授權資源路徑。
  • labels (對應，選用)：標記中繼資料鍵值組合，例如 env: production。
  • signatureDatabaseFile (字串，選用)：安全啟動簽章資料庫檔案的資源路徑。
  • storageLocations (字串陣列，選用)：目標儲存空間區域或多區域，例如 us-central1 或 us，Compute Engine 會將最終磁碟區塊儲存在這裡。注意：雖然這個屬性是以清單格式設定，但每個圖片目的地只能指定一個位置。

規格設定

套用一般執行作業選項：

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (布林值，選用)：切換測試 VM 是否評估啟動條件、網路和 UEFI 結構。預設值為 false。

規格步驟

指定 Image Builder 在 worker VM 上依序執行的步驟物件清單。如要查看每個步驟類型的完整輸入參數結構定義和使用範例，請參閱「支援的自訂動作」。

所有自訂步驟物件都具有下列共同屬性：

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..."

後續步驟