Memecahkan masalah kegagalan pipeline

Jika pipeline Image Builder gagal selama fase penyesuaian, tinjau file log, konfigurasi flag debug interaktif di worker VM, atau analisis image debug perantara untuk mengidentifikasi error waktu kompilasi atau skrip.

Sebelum memulai

  • Siapkan autentikasi jika Anda belum melakukannya. Autentikasi memverifikasi identitas Anda untuk mengakses layanan Google Cloud dan API. Untuk menjalankan kode atau sampel dari lingkungan pengembangan lokal, Anda dapat melakukan autentikasi ke Compute Engine dengan memilih salah satu opsi berikut:

    1. Instal Google Cloud CLI. Setelah penginstalan, inisialisasi Google Cloud CLI dengan menjalankan perintah berikut: 

      gcloud init

      Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

    2. Tetapkan region dan zona default.

Meninjau saluran logging

Image Builder menulis log ke beberapa lokasi untuk membantu Anda mendiagnosis kegagalan di berbagai tingkat stack:

  • Log orkestrator Cloud Build: Menampilkan langkah-langkah builder tingkat tinggi di Konsol Cloud Build. Jika langkah gagal, link ke direktori kerja Cloud Storage yang sesuai akan dicetak.
  • Log agen VM penyesuaian: Agen penyesuaian merekam output standar (stdout) dan error standar (stderr) dari langkah-langkah penyesuaian Anda. Orchestrator melakukan polling pada data ini dan melakukan streaming langsung ke log rekaman aktivitas Cloud Build. Jika log terpotong atau Anda perlu memeriksanya secara keseluruhan, buka folder yang cocok dengan ID build Anda di bucket _GCS_WORKDIR.
  • Serial console log: Jika OS tamu gagal di-boot, agen penyesuaian tidak dapat dimulai. Dalam kasus ini, lihat log konsol serial. Orchestrator mengalirkan output port serial VM pekerja langsung ke bucket workdir Cloud Storage Anda. Link ke file log serial dicetak di akhir rekaman aktivitas Cloud Build yang gagal.
  • Log jurnal OS tamu: Untuk pemecahan masalah tingkat sistem yang mendetail di Linux, agen penyesuaian mengupload salinan log journal sistem lengkap ke bucket workdir Cloud Storage Anda di akhir proses.

Menyelesaikan kegagalan skrip menggunakan tanda debug

Secara default, jika langkah penyesuaian gagal, Image Builder akan menghentikan eksekusi dan menghapus VM pekerja dengan segera untuk mengontrol biaya.

Untuk men-debug skrip secara interaktif, Anda dapat mengaktifkan tanda debug. Tindakan ini membuat VM tetap aktif, sehingga Anda dapat terhubung langsung ke sistem tamu yang aktif menggunakan SSH.

Aktifkan tanda debug

Di file imagebuilder.yaml, tetapkan debug: true di blok infrastructureConfig:

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

Picu build dan tunggu hingga gagal

Kirimkan build Anda menggunakan metode standar. Jika pipeline mengalami error skrip, hal berikut akan terjadi:

  1. Orchestrator menjeda eksekusi build.
  2. Image Builder tidak menghapus worker VM. Objek tersebut tetap berjalan di project Anda.
  3. VM akan tetap aktif selama waktu yang ditentukan dalam properti instanceDurationHours sebelum penghentian otomatis.

Menghubungkan ke VM pekerja untuk men-debug

Lihat output konsol Cloud Build untuk mengambil nama instance VM pekerja yang aktif. Buka terminal dan hubungkan ke VM pekerja menggunakan gcloud compute ssh:

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID

Jika file imagebuilder.yaml Anda mengonfigurasi externalIP: none, yang tidak menghasilkan alamat IP eksternal, sertakan tanda --tunnel-through-iap untuk terhubung dengan menggunakan penerusan TCP Identity-Aware Proxy (IAP):

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID \
    --tunnel-through-iap

Setelah terhubung, Anda dapat menjalankan perintah secara real time, memeriksa file target, menganalisis proses yang sedang berjalan, meninjau log histori penginstal, dan menguji modifikasi skrip langsung di disk.

Menganalisis gambar debug perantara

Sebagai alternatif untuk menjaga agar worker VM tetap aktif dengan flag debug, Anda dapat menganalisis status disk menggunakan image debug yang dibuat otomatis:

  1. Setiap kali build gagal dengan debug: false (default), orkestrator akan mengekspor boot disk yang disesuaikan sebagian sebagai image Compute Engine.
  2. Image debug diberi nama menggunakan pola image-builder-debug-image-BUILD_ID dan ditetapkan ke kelompok image image-builder-debug-images.

  3. Untuk memeriksa sistem file, buat instance VM sementara menggunakan image debug ini sebagai boot disk:

    gcloud compute instances create temp-debug-vm \
    --image-family=image-builder-debug-images \
    --zone=ZONE \
    --project=PROJECT_ID

  4. Hubungkan ke instance temp-debug-vm untuk memeriksa disk dan mengisolasi alasan kegagalan penyesuaian.

Menyelesaikan waktu tunggu Cloud Build

Jika proses Image Builder pipeline berjalan lebih lama dari yang diharapkan, tugas Cloud Build akan berhenti dan gagal dengan status TIMEOUT.

Waktu build dapat bervariasi dan biasanya lebih lama untuk jenis mesin yang lebih besar, jadi tetapkan waktu tunggu untuk memberikan lebih banyak waktu agar build selesai. Jika tidak ditetapkan, waktu tunggu Cloud Build default adalah 1 jam (3600s).

Untuk mengonfigurasi waktu tunggu yang lebih lama, tetapkan kolom timeout di tingkat root file cloudbuild.yaml Anda:

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'

Setelah memperbarui nilai waktu tunggu, jalankan kembali build dan verifikasi bahwa pipeline Image Builder dapat dieksekusi hingga selesai.

Untuk mengetahui informasi selengkapnya tentang parameter timeout, lihat timeout dalam dokumentasi Cloud Build.