File konfigurasi Cloud Build

Dokumen ini menjelaskan struktur dan parameter file konfigurasi Cloud Build (cloudbuild.yaml) yang digunakan untuk mengatur langkah-langkah pipeline Image Builder: parsing, build, validasi, dan publikasi rilis.

Ringkasan skema

File cloudbuild.yaml Image Builder standar mengikuti struktur file konfigurasi Cloud Build standar dan mengatur tiga langkah build container berurutan: /build, /validate, dan /publish.

substitutions:
  _GCS_WORKDIR: 'gs://BUCKET_NAME/workdir/'
  _IMAGE_BUILDER_CONFIG_PATH: 'imagebuilder.yaml'
  _SERVICE_ACCOUNT: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL'
  _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut'
  _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}'

steps:
  # Step 1: Parse configs and run OS customization on the worker VM
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /build
    id: 'imagebuilder-customize'
    results:
      - name: image_builder_telemetry_metrics
      - name: base_image
        attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"
        attestationContent: base_image

  # Step 2: Validate by running system boot checks on the test VM
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/validator:stable'
    script: |
      #!/usr/bin/env bash
      /validate
    id: 'imagebuilder-validate'
    results:
      - name: image_builder_telemetry_metrics

  # Step 3: Register OS image and publish tar file to Artifact Registry
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /publish
    id: 'imagebuilder-publish'
    results:
      - name: image_builder_telemetry_metrics

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

artifacts:
  generic_artifacts:
    - folder: '${_IMAGE_OUTPUT_PATH}'
      registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'

timeout: '3600s'

Variabel substitusi

File cloudbuild.yaml menggunakan variabel pengganti berikut untuk dipetakan langsung ke variabel lingkungan untuk dieksekusi:

substitutions:
  _GCS_WORKDIR: 'gs://BUCKET_NAME/workdir/'
  _IMAGE_BUILDER_CONFIG_PATH: 'imagebuilder.yaml'
  _SERVICE_ACCOUNT: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL'
  _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut'
  _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}'
  • _GCS_WORKDIR: Jalur Cloud Storage regional yang digunakan sebagai lokasi penyiapan sementara untuk artefak seperti log serial, arsip gambar sementara, dan histori eksekusi tamu. Bucket harus sudah ada.

  • _IMAGE_BUILDER_CONFIG_PATH: Jalur ke resep penyesuaian imagebuilder.yaml Anda. Ini dapat berupa jalur Cloud Storage jarak jauh (misalnya, gs://BUCKET_NAME/imagebuilder.yaml), atau jalur relatif di ruang kerja atau repositori GitHub Anda, bergantung pada sumbernya.

  • _SERVICE_ACCOUNT: Nama resource Identity and Access Management (IAM) lengkap dari akun layanan yang dikonfigurasi untuk menjalankan build dan mengizinkan langkah-langkah orkestrator.

  • _IMAGE_OUTPUT_PATH: Jalur output file tar yang diekspor di dalam direktori Cloud Build /workspace/.

  • _ARTIFACT_REGISTRY_RESOURCE_URI (Opsional): URI resource untuk repositori generik di Artifact Registry. Jika disediakan, pipeline akan mengirimkan file tar image imutable yang dibuat dan membuat pengesahan di lokasi ini.

Langkah

Image Builder menjalankan tiga langkah container yang berbeda secara berurutan untuk mengatur build image OS Anda. Ganti REGION di jalur image container dengan region Cloud de Confiance target tempat Anda menyiapkan pipeline, seperti us-central1, europe-west1, atau asia-east1:

steps:
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /build
    id: 'imagebuilder-customize'

  - name: 'REGION-docker.pkg.dev/image-builder-official/release/validator:stable'
    script: |
      #!/usr/bin/env bash
      /validate
    id: 'imagebuilder-validate'

  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /publish
    id: 'imagebuilder-publish'

Persyaratan telemetri dan ID langkah

Container orkestrator mengidentifikasi dan melacak progres setiap fase build—penyesuaian, validasi, dan publikasi—dengan membaca kolom id dari setiap langkah dalam file cloudbuild.yaml Anda.

ID langkah harus dimulai dengan awalan imagebuilder-, seperti imagebuilder-customize, imagebuilder-validate, dan imagebuilder-publish, agar Image Builder dapat mengumpulkan metrik telemetri spesifik per layanan.

Saat Anda menyertakan image_builder_telemetry_metrics dalam blok results di setiap langkah, Image Builder akan mengumpulkan metrik eksekusi pipeline tingkat tinggi secara aman untuk memantau dan melacak keandalan layanan sebagai berikut:

  • Eksekusi dan status build: Status berhasil atau gagal dan durasi penyelesaian untuk setiap langkah build dan tindakan penyesuaian.
  • Detail lingkungan: Jenis mesin, zona, dan tag versi penampung Compute Engine yang digunakan selama eksekusi.
  • Metadata image: Distribusi OS dasar, versi, dan fitur OS tamu yang dikonfigurasi.
  • Hasil pengujian validasi: Status lulus, gagal, atau dilewati dari pengujian validasi sistem otomatis, seperti booting VM, Booting Aman, kesehatan block storage, status agen tamu, dan pengikatan driver jaringan.

Langkah penyesuaian

Langkah penyesuaian memvalidasi skema imagebuilder.yaml, memeriksa izin IAM, meluncurkan instance VM pekerja, memasang disk biner penyesuaian, menjalankan penyedia penyesuaian, dan mengekspor partisi disk booting dengan aman.

  • Container image: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Perintah skrip: /build
  • Sub-blok hasil:
    • image_builder_telemetry_metrics: Mengumpulkan metrik eksekusi build penyesuaian.
    • base_image (Opsional): Mencatat detail gambar sumber dasar dalam metadata pengesahan build saat Anda menentukan tujuan repositori generik Artifact Registry. Setel attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions" untuk membuat catatan asal gambar Anda yang dapat diverifikasi.

Langkah validasi

Langkah validasi mem-boot VM pengujian sementara dari image OS yang disesuaikan dan menjalankan rangkaian pengujian validasi otomatis aktif.

  • Container image: us-central1-docker.pkg.dev/image-builder-official/release/validator:stable
  • Perintah skrip: /validate
  • Sub-blok hasil: image_builder_telemetry_metrics mengumpulkan metrik eksekusi pengujian validasi.

Langkah publikasi

Langkah publikasi mendaftarkan image OS akhir, menghapus disk perantara sementara, mengupload payload file tar ke Artifact Registry jika dikonfigurasi, dan menulis catatan asal Supply Chain Levels for Software Artifacts (SLSA).

  • Container image: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Perintah skrip: /publish
  • Sub-blok hasil: image_builder_telemetry_metrics mengumpulkan metrik eksekusi rilis publikasi.

Opsi

Flag opsi menentukan setelan eksekusi di server Cloud Build. Anda harus mengonfigurasi opsi berikut:

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

Untuk mengetahui informasi selengkapnya tentang setelan ini, lihat Opsi dalam file konfigurasi Cloud Build.

  • automapSubstitutions: Setel ke true untuk memastikan variabel penggantian dipetakan ke lingkungan container.
  • Tetapkan requestedVerifyOption ke VERIFIED. Setelan ini menginstruksikan Cloud Build untuk otomatis membuat pengesahan provenance build SLSA. Provenans ini memberikan verifikasi kriptografi bahwa image dibuat persis seperti yang ditentukan dalam pipeline Anda, sehingga membantu mencegah gangguan dan memastikan integritas rantai pasokan software.
  • Tetapkan substitutionOption ke ALLOW_LOOSE. Setelan ini diperlukan untuk memaksa Cloud Build mengabaikan parameter dinamis atau argumen skrip yang tidak digunakan.
  • dynamicSubstitutions: Setel ke true agar variabel evaluasi sistem, seperti ${BUILD_ID}, dapat diselesaikan dengan benar.
  • logging: Setel ke CLOUD_LOGGING_ONLY untuk membatasi log build secara ketat ke Cloud Logging.

Artefak

Konfigurasi blok artifacts saat Anda mengekspor arsip dan pengesahan gambar ke Artifact Registry:

artifacts:
  generic_artifacts:
    - folder: '${_IMAGE_OUTPUT_PATH}'
      registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'