本頁面的部分或所有資訊可能不適用於 S3NS 的 Cloud de Confiance。詳情請參閱「與 Google Cloud 的差異」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

支援的自訂動作

如要自訂虛擬機器映像檔，例如執行終端機指令碼、更新開機參數、轉移二進位檔或安裝 GPU 驅動程式，您可以在自訂食譜 (imagebuilder.yaml) 的 spec.steps 區塊中定義特定輔助動作。

總覽

在 Image Builder 建構作業的執行階段，worker VM 會依序執行自訂方案 (spec.steps) 中宣告的步驟。

每個步驟都必須指定 name、action 和 inputs 區塊，並根據動作類型進行調整。Image Builder 支援下列自訂動作：

Shell：在工作站客體 OS 上執行內嵌終端機指令碼或指令。
UpdateKernelCommandLine：修改啟動參數和核心指令列旗標。
FileCopy：將設定檔、指令碼或資產從 Cloud Storage 或本機工作區轉移至 VM。
InstallGPU：下載、編譯及註冊 NVIDIA GPU 驅動程式。

殼層動作

Shell 動作可讓您在臨時工作站 VM 的客體 OS 上執行內嵌終端機指令碼或單一殼層命令，以執行自訂作業，例如更新套件、設定使用者帳戶或編譯軟體。

在 steps.inputs 下方指定下列任一輸入內容：

inlineScript (字串)：要執行的原始多行殼層指令。
command (字串)：單一系統指令字串，或可執行二進位檔案的相對路徑。

範例設定

下列分頁標籤顯示執行內嵌指令碼與執行單一指令的範例步驟設定：

執行內嵌指令碼

下列設定會執行多行指令碼，使用 apt 更新套件：

- 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 完整性雜湊記錄到建構記錄中。這個雜湊值提供不可變動的稽核追蹤記錄，可確切瞭解映像檔上執行的程式碼。

系統重新啟動 (結束代碼 3010)

部分殼層動作 (例如核心修補程式更新或儲存空間分割區調整) 需要重新啟動系統，後續步驟才能執行。

如要在自訂期間要求系統重新啟動，您的殼層指令碼必須以 exit 3010 指令結尾。自訂佈建工具收到結束代碼 3010 時，會依下列方式處理重新啟動生命週期：

佈建器會偵測到結束代碼 3010、暫停執行，並標示步驟進度索引。
佈建工具會重新啟動 worker VM。
VM 重新啟動後，佈建工具會掛接工作區，並自動在佇列中的下一個步驟繼續執行管道。

重新啟動範例：

以下範例顯示更新套件並要求重新啟動的步驟設定：

- 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 屬性中設定的參數。

範例設定

以下分頁標籤顯示範例步驟設定，說明如何取代或移除核心啟動引數：

取代開機引數

以下設定會找出核心記錄層級鍵 loglevel=4，並以更詳細的參數 loglevel=6 console=ttyS0 取代：

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

移除開機引數

下列設定會搜尋 quiet 參數，並從啟動引數中移除，以便在啟動檢查階段啟用詳細記錄：

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

特定 OS 的執行作業詳細資料

以下分頁說明自訂佈建工具如何根據來源客體作業系統處理映像檔修改作業：

Container-Optimized OS (COS)

由於 COS 採用唯讀分割區版面配置，因此省略了標準設定工具。自訂佈建程式會執行下列作業：

判斷使用中的開機裝置路徑。
掛接啟動裝置的第 12 個分割區 (EFI 分割區)。
直接更新 /efi/boot/grub.cfg 內的開機載入程式參數。
安全卸載分區 12。

Ubuntu

在 Ubuntu 映像檔中，自訂佈建程式會執行下列作業：

開啟 /etc/default/grub 和 /etc/default/grub.d/*.cfg 下的檔案。
插入、修改或刪除 GRUB_CMDLINE_LINUX 區塊下的目標引數。
執行套件指令 update-grub，重新產生開機載入程式設定。

FileCopy 動作

FileCopy 動作會將設定檔、二進位檔或憑證從遠端 bucket 或本機存放區複製到自訂映像檔。自訂佈建工具會下載或讀取來源檔案、將檔案寫入 worker VM 上指定的訪客路徑，並設定權限。

在 steps.inputs 下方指定下列輸入內容：

destination (字串，必要)：訪客 OS 中建立檔案的絕對路徑。
permissions (字串，必填)：目標設定權限的八進位表示法，例如 "0755" 或 "0644"。
指定下列任一來源屬性：
- gcsSourcePath (字串)：來源檔案的 Cloud Storage URI，格式必須為 gs://BUCKET_NAME/OBJECT_NAME。
- localSourcePath (字串)：本機工作區存放區資料夾中檔案的相對路徑。為確保安全，系統已封鎖使用 ../ 的路徑遍歷。

範例設定

以下分頁顯示複製檔案的範例步驟設定，分別是從 Cloud Storage 複製，以及從本機工作區複製：

Cloud Storage

以下設定會將 Cloud Storage bucket 中的設定範本複製到訪客 VM 映像檔：

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

本機工作區

下列設定會複製先前 Cloud Build 步驟中編譯的應用程式指令碼：

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

特定作業系統的規範

下列分頁說明檔案位置規範，視目標客體作業系統而定：

Container-Optimized OS (COS)

為確保安全，COS 映像檔包含唯讀分割區配置。部分標準系統目標 (例如 /usr/ 或 /bin/) 受到防寫保護。

在 COS 上設定檔案目的地時：

請只在可寫入的具狀態位置指定檔案，例如 /var 或 /home。
請參閱官方的「Container-Optimized OS 磁碟和檔案系統參考資料」，找出適當的路徑。

Ubuntu

Ubuntu 映像檔採用標準 Linux 讀寫根分割區版面配置 (/)。您可以在任何標準系統路徑中指定檔案目的地，例如 /etc、/usr/local/bin、/var 或 /home，前提是使用者設定檔或目的地資料夾在 worker VM 上具有適當的設定權限。

InstallGPU 動作

使用 InstallGPU 動作建構針對機器學習、資料科學或科學工作負載最佳化的 VM 映像檔。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 檔案在本地工作區存放區資料夾中的相對路徑。

範例設定

以下分頁標籤顯示安裝特定預先封裝驅動程式版本，以及安裝自訂執行檔的步驟設定範例：

下載標準版

以下設定會從官方存放區下載並安裝指定的 NVIDIA 驅動程式版本：

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

Cloud Storage 執行檔

下列設定會直接從 Cloud Storage bucket 部署自訂 NVIDIA 驅動程式 .run 安裝程式：

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

本機工作區執行檔

下列設定會從本機存放區工作區部署自訂 NVIDIA 驅動程式 .run 安裝程式：

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

設定方法

以下分頁說明在自訂映像檔上設定 NVIDIA GPU 驅動程式的支援方法：

預先編譯的驅動程式

建議使用預先封裝的驅動程式版本，以免從頭編譯驅動程式，造成運算負擔和建構時間。

Container-Optimized OS (COS)：如果您指定 Google 預先封裝的驅動程式版本，自訂佈建工具會執行客體工具 cos-extensions install gpu 來啟用該版本。

如要查看 COS 版本支援的預先編譯驅動程式版本清單，請在執行中的 COS 執行個體上執行 sudo cos-extensions list，或參閱「找出 GPU 驅動程式版本」。
Ubuntu：如要節省 Ubuntu 的建構時間，建議從公開的 ubuntu-os-accelerator-images 專案中選取預先設定的基本映像檔，其中已預先安裝 NVIDIA 驅動程式。

如要列出可用的加速器映像檔，請在 gcloud CLI 中執行下列指令：
```
gcloud compute images list \
    --project=ubuntu-os-accelerator-images \
    --no-standard-images
```

自訂執行檔案

如果必須安裝非 Google 或 Canonical 預先編譯的自訂驅動程式版本，您可以指定直接安裝程式執行檔進行編譯，如下所示：

Ubuntu：執行客內編譯作業。自訂佈建工具會自動安裝相符的核心標頭 (linux-headers-$(uname -r))，在 worker VM 上編譯 NVIDIA 驅動程式 .run 檔案，並向動態核心模組支援 (DKMS) 註冊。向 DKMS 註冊可確保驅動程式在次要核心更新期間保持啟用狀態。
Container-Optimized OS (COS)：編譯行為會因來源基礎 VM 映像檔的 CPU 架構而異：
- ARM64 映像檔：由於 ARM64 COS VM 不支援客體內標頭編譯，因此 Image Builder 會在建構容器中自動交叉編譯自訂驅動程式 .run 公用程式，並將產生的套件安裝至工作站 VM 的 /var/lib/nvidia 中。
- x86-64 映像檔：直接在工作者 VM 上執行客內編譯。

後續步驟

查看圖片自訂檔案結構定義中的頂層結構定義區塊。
在 Cloud Build 建構設定檔結構定義中設定管道自動化調度管理參數。
按照教學課程建立 Image Builder 管道。