File penyesuaian gambar

Dokumen ini menjelaskan struktur dan parameter file resep penyesuaian, imagebuilder.yaml, yang Anda gunakan untuk menentukan image OS dasar, konfigurasi hardware, tujuan rilis, dan tindakan penyesuaian untuk pipeline Image Builder Anda.

Ringkasan skema

Konfigurasi penyesuaian menggunakan versi API imagebuilder.gcp.com/v1 dan jenis resource OSImageCustomization.

File resep standar memiliki struktur berikut:

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
  name: CONFIG_NAME
  description: DESCRIPTION
infrastructureConfig:
  # VM machine type, zone, and network settings
  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: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
source:
  # Base source image profile
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY
  # Alternatively, use a direct image version URI:
  # imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
destinations:
  # Output OS image release targets
  - 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:
        - STORAGE_LOCATION
spec:
  config:
    # Build options and validation test flags
    skipSystemTests: false
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters

Metadata

Memberikan detail identifikasi untuk template build kustom ini:

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (string, Wajib): ID untuk konfigurasi ini.
  • description (string, Opsional): Deskripsi tujuan build.

Konfigurasi infrastruktur

Menentukan properti hardware dan jaringan instance virtual machine sementara yang dibuat Image Builder selama tugas build dan validasi:

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: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
  • machineType (string, Wajib): Jenis mesin Compute Engine yang akan digunakan untuk VM pekerja dan pengujian. Pastikan jenis mesin cocok dengan arsitektur image sumber yang Anda tentukan di imageFamily atau imagePath. Misalnya, gunakan e2-standard-4 untuk image x86 dan c4a-standard-4 untuk image Arm. Jenis mesin bare metal tidak didukung.
  • zone (string, Wajib): Zona tempat VM pekerja dan pengujian berjalan, seperti us-central1-a.
  • network (string, Opsional): Jaringan VPC yang akan dilampirkan ke VM pengujian validasi dan pekerja, seperti projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> atau default. Jika dihilangkan, Image Builder akan menggunakan jaringan default.
  • subnetwork (string, Opsional): Subjaringan VPC yang akan dilampirkan ke VM pengujian validasi dan pekerja, seperti projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>.
  • externalIP (string, Opsional): Menentukan alokasi alamat IP eksternal untuk VM pengujian validasi dan pekerja. Nilai yang diizinkan:
    • ephemeral (default): Mengalokasikan alamat IPv4 efemeral publik dari kumpulan bersama.
    • none: Membuat VM tanpa alamat IP eksternal, yang hanya menggunakan jaringan VPC pribadi. Jika disetel ke none, pastikan subnetwork VPC Anda telah mengaktifkan Akses Google Pribadi atau Cloud NAT sehingga VM dapat mengakses layanan dan repositori paket yang diperlukan Cloud de Confiance .
  • acceleratorType (string, Opsional): Jenis akselerator GPU yang akan dilampirkan ke worker VM, seperti nvidia-tesla-t4 atau nvidia-l4.
  • acceleratorCount (angka, Opsional): Jumlah akselerator GPU yang akan dipasang ke VM pekerja.
  • debug (boolean, Opsional): Jika Anda menyetel debug ke true, Image Builder akan mempertahankan worker VM, baik penyesuaian selesai maupun gagal, sehingga Anda dapat memeriksa atau memecahkan masalah instance aktif menggunakan SSH. Setelan defaultnya adalah false.
  • instanceDurationHours (angka, Opsional): Membatasi runtime worker VM. Batas waktu dimulai saat penyesuaian selesai atau mengalami error skrip, sehingga Anda dapat terhubung ke VM aktif selama sesi debug interaktif. Dibatasi hingga maksimum 2.0 jam.
  • reservations (array string, Opsional): Nama resource reservasi kapasitas (seperti test-reservation dalam project yang sama) yang akan digunakan saat Image Builder membuat VM.
  • validationConcurrency (angka, Opsional): Menentukan jumlah maksimum uji validasi yang akan dijalankan secara paralel pada instance komputasi uji validasi sementara. Nilai yang diizinkan mencakup:
    • 0 atau dihilangkan (default): Image Builder otomatis mendeteksi konkurensi berdasarkan jenis mesin dan konfigurasi akselerator, lalu menyetelnya sebagai berikut:
      • 1 (berurutan) untuk jenis atau konfigurasi mesin bare metal dengan akselerator GPU terpasang, yang membantu mencegah terlampauinya batas kuota atau kehabisan resource.
      • 4 (paralel) untuk semua jenis mesin lainnya.
    • 1: Menjalankan uji validasi secara berurutan. Jika project Anda memiliki kuota terbatas untuk machineType yang ditentukan, menetapkan konkurensi ke 1 dapat membantu karena mencegah beberapa instance komputasi dimulai secara bersamaan.
    • 2 atau lebih besar: Menjalankan jumlah pengujian validasi yang ditentukan secara paralel. Jika Anda memiliki kapasitas atau pemesanan yang memadai, peningkatan konkurensi dapat mengurangi waktu eksekusi keseluruhan untuk pengujian validasi.

Gambar sumber

Mengidentifikasi image sistem operasi dasar yang digunakan Image Builder untuk meluncurkan VM pekerja. Anda harus menentukan salah satu opsi berikut:

Untuk menentukan kelompok image standar:

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

Untuk menentukan URI versi gambar langsung:

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily (string): Jalur ke grup keluarga image standar, seperti projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts.
  • imagePath (string): URI resource langsung ke versi image Compute Engine tertentu, seperti projects/cos-cloud/global/images/cos-105-17412-226-28.

Tujuan

Menentukan tempat dan cara merilis image OS kustom yang dikompilasi. Properti ini berisi daftar objek tujuan rilis di bagian 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:
        - STORAGE_LOCATION
  • name (string, Wajib): Awalan nama dasar yang ditetapkan ke resource image Compute Engine akhir. Image Builder secara otomatis menambahkan ID build unik ke awalan ini dan memangkas nama akhir image hingga 63 karakter.
  • family (string, Opsional): Kelompok gambar yang akan diterapkan ke gambar yang baru dibuat.
  • project (string, Wajib): Project Cloud de Confiance tempat Image Builder menulis image output.
  • description (string, Opsional): Teks deskripsi yang dilampirkan ke metadata gambar yang dihasilkan.
  • licenses (array string, Opsional): Jalur resource lisensi software tertentu yang diterapkan pada gambar ini.
  • labels (peta, Opsional): Menandai pasangan nilai kunci metadata, seperti env: production.
  • signatureDatabaseFile (string, Opsional): Jalur resource ke file database tanda tangan boot aman.
  • storageLocations (array string, Opsional): Target region atau multi-region penyimpanan, seperti us-central1 atau us, tempat Compute Engine menyimpan blok disk akhir. Catatan: Meskipun diformat sebagai daftar, Anda hanya dapat menentukan satu lokasi per tujuan gambar.

Konfigurasi spesifikasi

Menerapkan opsi eksekusi umum:

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (boolean, Opsional): Mengalihkan apakah VM pengujian mengevaluasi kondisi booting, jaringan, dan struktur UEFI. Nilai defaultnya adalah false.

Langkah-langkah spesifikasi

Menentukan daftar objek langkah yang dijalankan Image Builder secara berurutan di worker VM. Untuk mengetahui skema parameter input dan contoh penggunaan lengkap untuk setiap jenis langkah, lihat Tindakan penyesuaian yang didukung.

Semua objek langkah penyesuaian memiliki properti umum berikut:

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (string, Wajib): Nama yang ditentukan pengguna untuk langkah penyesuaian ini.
  • action (string, Wajib): Tindakan helper yang akan dipanggil. Tindakan yang didukung:
  • inputs (objek, Wajib): Properti kunci-nilai yang diperlukan oleh tindakan yang dipilih. Untuk mengetahui referensi dan contoh parameter lengkap, lihat Tindakan penyesuaian yang didukung.

Cuplikan berikut menunjukkan contoh langkah menggunakan tindakan Shell:

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

Langkah berikutnya