排解管道失敗問題

如果 Image Builder 管道在自訂階段失敗，請檢查記錄檔、在工作者 VM 上設定互動式偵錯標記，或分析中繼偵錯映像檔，找出編譯時間或指令碼錯誤。

事前準備

  • 如果尚未設定驗證，請先完成設定。 驗證可確認您的身分，以便存取 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 workdir 目錄連結。
  • 自訂 VM 代理程式記錄：自訂代理程式會擷取自訂步驟的標準輸出 (stdout) 和標準錯誤 (stderr)。自動調度管理工具會輪詢這些記錄，並直接將記錄串流至 Cloud Build 追蹤記錄。如果記錄遭到截斷，或您需要檢查完整記錄，請前往 _GCS_WORKDIR bucket 中與建構 ID 相符的資料夾。
  • 序列控制台記錄：如果客體 OS 無法啟動，自訂代理程式就無法啟動。在這種情況下，請查看序列主控台記錄。協調器會將工作站 VM 的序列埠輸出內容，直接串流至 Cloud Storage 工作目錄 bucket。失敗的 Cloud Build 追蹤記錄結尾會列印序列記錄檔的連結。
  • 客層 OS 記錄檔：如要對 Linux 進行詳細的系統層級疑難排解，自訂代理會在執行結束時，將完整的系統 journal 記錄檔副本上傳至 Cloud Storage 工作目錄值區。

使用偵錯標記解決指令碼失敗問題

根據預設，如果自訂步驟失敗，為控管費用，Image Builder 會立即終止執行作業並刪除 worker VM。

如要以互動方式偵錯指令碼，可以啟用 debug 標記。這樣 VM 就能保持運作，您可以使用 SSH 直接連線至運作中的客體系統。

啟用偵錯旗標

在 imagebuilder.yaml 檔案中，於 infrastructureConfig 區塊下方設定 debug: true：

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

觸發建構作業並等待失敗

使用標準方法提交建構版本。如果管道發生指令碼錯誤，會出現下列情況：

  1. 自動化調度管理工具會暫停建構作業。
  2. Image Builder 不會刪除 worker VM。專案中仍會繼續執行。
  3. VM 會在自動終止前，保持活動狀態一段時間，這段時間長度由 instanceDurationHours 屬性指定。

連線至 worker VM 以進行偵錯

查看 Cloud Build 控制台輸出內容，擷取作用中工作站 VM 執行個體的名稱。開啟終端機，然後使用 gcloud compute ssh 連線至 worker VM：

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 旗標讓 worker VM 保持啟用狀態，您也可以使用自動生成偵錯映像檔分析磁碟狀態：

  1. 如果建構作業失敗 (預設為 debug: false)，協調器會將部分自訂的開機磁碟匯出為 Compute Engine 映像檔。
  2. 偵錯映像檔會以 image-builder-debug-image-BUILD_ID 模式命名，並指派給 image-builder-debug-images 映像檔系列。

  3. 如要檢查檔案系統，請使用這個偵錯映像檔做為開機磁碟，建立臨時 VM 執行個體：

    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'

更新逾時值後，請重新執行建構作業，並確認 Image Builder 管道能夠執行完畢。

如要進一步瞭解 timeout 參數，請參閱 Cloud Build 說明文件中的 timeout。