Membuat pipeline image OS kustom menggunakan gcloud atau Terraform

Konfigurasi dan kirim pipeline Image Builder secara terprogram menggunakan Google Cloud CLI atau Terraform. Mengonfigurasi pipeline secara terprogram memungkinkan Anda menentukan setelan infrastruktur, image OS dasar, tindakan penyesuaian, dan pengujian validasi dalam file konfigurasi deklaratif.

Sebelum memulai

  • Selesaikan langkah-langkah penyiapan lingkungan di Menyiapkan lingkungan Anda.
  • Jika Anda ingin men-deploy pipeline menggunakan Terraform atau mengotomatiskan build dari repositori, hubungkan repositori GitHub, GitLab, atau Bitbucket Anda menggunakan repositori Cloud Build (2nd gen) atau link koneksi Developer Connect.
  • Jika Anda berencana menggunakan Terraform, instal the Terraform CLI versi 1.3 atau yang lebih baru.
  • Siapkan autentikasi jika Anda belum melakukannya. Autentikasi memverifikasi identitas Anda untuk mengakses Google Cloud layanan dan API. Untuk menjalankan kode atau contoh dari lingkungan pengembangan lokal, Anda dapat melakukan autentikasi ke Compute Engine dengan memilih salah satu opsi berikut:

    Pilih tab untuk melihat bagaimana Anda berencana menggunakan contoh di halaman ini:

    gcloud

    1. Instal Google Cloud CLI, lalu login ke gcloud CLI dengan identitas gabungan Anda. Setelah login, inisialisasi Google Cloud CLI dengan menjalankan perintah berikut: 

      gcloud init
  • Tetapkan region dan zona default.

    • Terraform

    Untuk menggunakan contoh Terraform di halaman ini dalam lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

    1. Instal Google Cloud CLI.

    2. Konfigurasi gcloud CLI agar menggunakan identitas gabungan Anda.

      Untuk mengetahui informasi selengkapnya, lihat Login ke gcloud CLI dengan identitas gabungan Anda.

    3. Buat kredensial autentikasi lokal untuk akun pengguna Anda: 

      gcloud auth application-default login

      Jika error autentikasi ditampilkan, dan Anda menggunakan penyedia identitas (IdP) eksternal, pastikan Anda telah login ke gcloud CLI dengan identitas gabungan Anda.

    Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk membuat dan mengirimkan pipeline penyesuaian image menggunakan Google Cloud CLI atau Terraform, minta administrator untuk memberi Anda peran IAM berikut di project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Membuat file konfigurasi

Untuk mengonfigurasi pipeline menggunakan gcloud CLI atau Terraform, buat dua file konfigurasi:

  • imagebuilder.yaml: menentukan urutan langkah penyesuaian untuk image, termasuk OS image dasar, setelan infrastruktur worker VM, detail output image target, dan langkah-langkah penyesuaian berurutan seperti menjalankan skrip shell, mentransfer file, atau melakukan reboot.
  • cloudbuild.yaml: mengatur langkah-langkah proses build di Cloud Build, termasuk mengurai, memvalidasi, membangun, menguji, dan memublikasikan image OS kustom.

Membuat file konfigurasi image

Untuk menentukan konfigurasi image, buat file bernama imagebuilder.yaml di direktori lokal Anda. Untuk mengetahui daftar lengkap semua kolom skema dan tindakan penyesuaian, lihat Skema resep penyesuaian dan Tindakan penyesuaian yang didukung.

Contoh file imagebuilder.yaml berikut mengonfigurasi pipeline yang membangun image Ubuntu 22.04 LTS yang disesuaikan menggunakan worker VM e2-standard-4 di region dan zona yang Anda tentukan, serta melakukan update paket sistem.

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  name: customized-ubuntu-baseline
  description: "Ubuntu 22.04 LTS custom OS baseline image"
infrastructureConfig:
  machineType: e2-standard-4
  zone: ZONE
  debug: false
source:
  imageFamily: projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts
destinations:
  - diskImage:
      name: custom-ubuntu-v1
      family: custom-ubuntu-family
      project: PROJECT_ID
      storageLocations:
        - REGION
spec:
  config:
    skipSystemTests: false
  steps:
    -   name: "System Package Update"
      action: Shell
      inputs:
        command: "apt-get update -y && apt-get upgrade -y"

Ganti nilai placeholder berikut:

  • PROJECT_ID: project ID Anda.
  • REGION: lokasi penyimpanan image target, misalnya, us-east1 atau europe-west1. Pastikan Anda memenuhi persyaratan regional dan zona berikut:
    • Image Builder hanya didukung di region tempat Cloud Build tersedia.
    • ZONE worker VM harus berada dalam REGION yang Anda tentukan.
    • Untuk meminimalkan latensi jaringan dan mencegah biaya traffic keluar lintas-region, pastikan zona worker VM, bucket staging Cloud Storage, repositori Artifact Registry, dan lokasi penyimpanan image target berada di region yang sama.
  • ZONE: zona yang berada dalam REGION yang Anda tentukan, misalnya, us-east1-b atau europe-west1-b.

Membuat file build orkestrator

Buat file bernama cloudbuild.yaml di direktori yang sama. File ini memanggil langkah-langkah container Image Builder untuk membangun, memvalidasi, dan memublikasikan image OS kustom.

substitutions:
  _GCS_WORKDIR: 'gs://STAGING_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 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 a 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 image in Compute Engine and upload tar files 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'

Ganti nilai placeholder berikut:

  • STAGING_BUCKET_NAME: bucket Cloud Storage yang ada di project Anda untuk digunakan sebagai ruang kerja staging sementara. Jika tidak memiliki bucket, Anda dapat membuatnya dengan menjalankan gcloud storage buckets create gs://STAGING_BUCKET_NAME. Jika Anda men-deploy pipeline menggunakan Terraform, Terraform akan membuat bucket ini secara otomatis.
  • PROJECT_ID: project ID Anda Google Cloud .
  • REGION: Google Cloud region untuk repositori Artifact Registry Anda, misalnya, us-east1 atau europe-west1.
  • SERVICE_ACCOUNT_EMAIL: email untuk akun layanan yang Anda konfigurasi dengan izin IAM yang diperlukan.
  • REPOSITORY dan PACKAGE: repositori target dan nama paket yang dibuat di Artifact Registry. Untuk menyiapkan registry Artifact Registry, lihat Mengonfigurasi Artifact Registry.

Membuat dan mengirimkan pipeline build

Untuk menjalankan pipeline penyesuaian image, kirim build menggunakan gcloud CLI atau deploy pipeline menggunakan Terraform. Pilih salah satu tab berikut:

gcloud

Untuk men-deploy dan menjalankan pipeline penyesuaian image, dari terminal lokal Anda direktori yang berisi kedua file konfigurasi, jalankan gcloud builds submit perintah:

gcloud builds submit . \
    --config=cloudbuild.yaml \
    --project=PROJECT_ID \
    --service-account="projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL" \
    --region=REGION

Ganti kode berikut:

  • PROJECT_ID: project ID Anda Google Cloud .
  • REGION: Google Cloud region untuk menjalankan tugas pipeline penyesuaian image Anda.
  • SERVICE_ACCOUNT_EMAIL: alamat email akun layanan yang dikonfigurasi dengan izin IAM yang diperlukan.

Perintah ini mengupload ruang kerja penyesuaian Anda, mendaftarkan eksekusi Cloud Build, dan meluncurkan container orkestrasi.

Terraform

Untuk menyediakan infrastruktur yang diperlukan untuk membangun dan memvalidasi image OS yang disesuaikan secara otomatis, Anda dapat menggunakan Terraform. Konfigurasi Terraform ini menyelesaikan tugas berikut:

  • MengaktifkanAPI yang diperlukan Google Cloud .
  • Membuat bucket Cloud Storage khusus (workdir_bucket) untuk menyimpan log sementara dan artefak build.
  • Mengonfigurasi pemicu Cloud Build (image_builder_trigger) yang ditautkan ke koneksi repositori GitHub Developer Connect Anda.

Membuat file konfigurasi Terraform

Untuk mengatur dan men-deploy infrastruktur pipeline menggunakan Terraform, selesaikan langkah-langkah berikut:

  1. Buat direktori khusus di workstation lokal atau lingkungan CI/CD, terpisah dari repositori aplikasi Anda, lalu ubah ke direktori tersebut:

    mkdir terraform-image-builder && cd terraform-image-builder

  2. Di direktori ini, buat lima file konfigurasi Terraform berikut:

    • terraform.tfvars: menetapkan nilai untuk variabel khusus project.
    • main.tf: menyediakan resource di Google Cloud project Anda, termasuk mengaktifkan API yang diperlukan, membuat bucket staging Cloud Storage (workdir_bucket), dan men-deploy pemicu Cloud Build (image_builder_trigger).
    • outputs.tf: menentukan nilai output yang ditampilkan di terminal Anda setelah deployment, seperti ID pemicu dan nama bucket staging.
    • providers.tf: menentukan versi Terraform yang diperlukan (>= 1.3) dan mengonfigurasi Google Cloud penyedia (hashicorp/google).
    • variables.tf: menentukan variabel input, nilai default, dan aturan validasi untuk deployment.

    Pilih salah satu tab berikut untuk melihat dan menyalin konfigurasi setiap file ke direktori lokal Anda:

    terraform.tfvars

    File ini menentukan nilai parameter untuk lingkungan Anda untuk variabel yang dideklarasikan:

    project_id                = "PROJECT_ID"
builder_service_account   = "SERVICE_ACCOUNT_EMAIL"
github_repo_name          = "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION/repositories/REPO_NAME"
region                    = "REGION"
trigger_name              = "TRIGGER_NAME"
cloudbuild_yaml_path      = "CLOUDBUILD_YAML_PATH"
image_builder_config_path = "RECIPE_PATH"
gcs_lifecycle_age_days    = LIFECYCLE_DAYS
ar_repository_id          = "REPOSITORY_NAME"
ar_package_name           = "PACKAGE_NAME"

    Ganti placeholder berikut untuk resource yang sudah ada:

    • PROJECT_ID: project ID Anda yang ada Google Cloud .
    • SERVICE_ACCOUNT_EMAIL: alamat email akun layanan build Anda yang dikonfigurasi di Mengonfigurasi akun layanan Image Builder.
    • LOCATION, CONNECTION, dan REPO_NAME: region host, nama koneksi, dan link repositori Developer Connect Anda yang dikonfigurasi di Menghubungkan repositori.
    • CLOUDBUILD_YAML_PATH: jalur relatif ke file cloudbuild.yaml Anda di direktori lokal Anda. Anda tidak perlu memeriksa cloudbuild.yaml ke repositori Git Anda.
    • RECIPE_PATH: jalur relatif ke file resep penyesuaian imagebuilder.yaml Anda yang diperiksa ke repositori Git Anda.
    • REPOSITORY_NAME: repositori Artifact Registry generik yang ada dan dibuat di Mengonfigurasi Artifact Registry.

    Ganti placeholder berikut untuk resource yang dibuat Terraform:

    • REGION: region target Google Cloudtempat Terraform menyediakan bucket staging Cloud Storage dan pemicu Cloud Build, misalnya, us-central1.
    • TRIGGER_NAME: nama untuk pemicu repositori Cloud Build baru yang dibuat oleh Terraform, misalnya, git-push-os-builder.
    • LIFECYCLE_DAYS: periode retensi dalam hari sebelum artefak perantara di bucket staging Cloud Storage yang dibuat oleh Terraform dihapus secara otomatis, misalnya, 30.
    • PACKAGE_NAME: nama yang Anda inginkan untuk digunakan Terraform untuk paket yang dibuat di dalam repositori Artifact Registry Anda. Paket ini menyimpan versi image OS yang dipublikasikan, misalnya, ubuntu-custom.

    main.tf

    File ini mendeklarasikan resource infrastruktur inti dan sumber data untuk deployment:

    # Main resource configurations for Image Builder.
# 1. Enable Required APIs
resource "google_project_service" "apis" {
  for_each = toset([
    "compute.googleapis.com",
    "cloudbuild.googleapis.com",
    "artifactregistry.googleapis.com",
    "serviceusage.googleapis.com",
    "cloudresourcemanager.googleapis.com",
    "iam.googleapis.com",
    "storage.googleapis.com"
  ])
  project = var.project_id
  service = each.key
  disable_on_destroy = false
}

# 2. Project data source to retrieve Project Number
data "google_project" "project" {
  project_id = var.project_id
  depends_on = [google_project_service.apis]
}

locals {
  builder_sa = var.builder_service_account
}

# 3. Storage Bucket for Image Builder Workdir
resource "google_storage_bucket" "workdir_bucket" {
  name                        = var.gcs_bucket_name != "" ? var.gcs_bucket_name : "${var.project_id}-vm-builder-workdir"
  project                     = var.project_id
  location                    = var.region
  force_destroy               = true
  uniform_bucket_level_access = true
  lifecycle_rule {
    action {
      type = "Delete"
    }
    condition {
      age = var.gcs_lifecycle_age_days
    }
  }
  depends_on = [google_project_service.apis]
}

# 4. Cloud Build Trigger
resource "google_cloudbuild_trigger" "image_builder_trigger" {
  name        = var.trigger_name
  location    = var.region
  project     = var.project_id
  description = "Trigger that runs Image Builder customization"

  service_account = var.builder_service_account != "" ? "projects/${var.project_id}/serviceAccounts/${var.builder_service_account}" : null

  repository_event_config {
    repository = replace(var.github_repo_name, "gitRepositoryLinks", "repositories")
    push {
      branch = "^main$"
    }
  }
  filename = var.cloudbuild_yaml_path

  substitutions = {
    _GCS_WORKDIR                    = "gs://${google_storage_bucket.workdir_bucket.name}/workdir/"
    _SERVICE_ACCOUNT                = "projects/${var.project_id}/serviceAccounts/${local.builder_sa}"
    _IMAGE_OUTPUT_PATH              = "image-builder/binaryOut"
    _PROJECT_ID                     = var.project_id
    _LOCATION                       = var.region
    _REPOSITORY_NAME                = var.ar_repository_id
    _PACKAGE_NAME                   = var.ar_package_name
    _IMAGE_BUILDER_CONFIG_PATH      = var.image_builder_config_path
    _ARTIFACT_REGISTRY_RESOURCE_URI = "projects/${var.project_id}/locations/${var.region}/repositories/${var.ar_repository_id}/packages/${var.ar_package_name}/versions/v$${BUILD_ID}"
  }
  depends_on = [
    google_project_service.apis
  ]
}

    outputs.tf

    File ini menentukan atribut output yang ditampilkan ke terminal Anda setelah deployment:

    output "builder_service_account" {
  value       = local.builder_sa
  description = "The email representation of the resolved Image Builder service account."
}

output "workdir_bucket" {
  value       = google_storage_bucket.workdir_bucket.name
  description = "The name of the storage workdir bucket."
}

output "artifact_registry_repository" {
  value       = "projects/${var.project_id}/locations/${var.region}/repositories/${var.ar_repository_id}"
  description = "The fully qualified resource path of the Artifact Registry repository."
}

output "cloud_build_trigger_id" {
  value       = google_cloudbuild_trigger.image_builder_trigger.trigger_id
  description = "The unique ID for the created Cloud Build Trigger."
}

    providers.tf

    File ini mengonfigurasi setelan region dan versi Terraform yang diperlukan:

    terraform {
  required_version = ">= 1.3"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 5.0, < 7.0"
    }
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

    variables.tf

    File ini mendeklarasikan semua variabel input dan aturan validasi yang diperlukan dan opsional:

    variable "project_id" {
  type        = string
  description = "The target Project ID where resources will be created."
  validation {
    condition     = can(regex("^[a-z0-9-]{6,30}$", var.project_id))
    error_message = "The project_id must consist of lowercase letters, numbers, and hyphens, and be between 6 and 30 characters."
  }
}

variable "region" {
  type        = string
  default     = "us-central1"
  description = "Location used for cloud build triggers, storage buckets, and artifact registry."
}

variable "github_repo_name" {
  type        = string
  default     = ""
  description = "Developer Connect github repository details, format: projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION/repositories/REPO_LINK"
  validation {
    condition     = can(regex("^projects/[^/]+/locations/[^/]+/connections/[^/]+/(gitRepositoryLinks|repositories)/[^/]+$", var.github_repo_name))
    error_message = "The github_repo_name must follow either the Cloud Build v2 repository link format (using '/repositories/') or the Developer Connect resource format (using '/gitRepositoryLinks/')."
  }
}

variable "builder_service_account" {
  type        = string
  default     = ""
  description = "The email representation of the pre-existing Image Builder service account. If omitted, the default Cloud Build service account will be used."
}

variable "gcs_bucket_name" {
  type        = string
  default     = ""
  description = "Custom name for the workdir storage bucket. If left empty, a default name using the project ID will be constructed."
}

variable "gcs_lifecycle_age_days" {
  type        = number
  default     = 30
  description = "The number of days after which temporary logs and artifacts in the storage workdir bucket are deleted."
}

variable "ar_repository_id" {
  type        = string
  default     = "vm-images"
  description = "The repository ID for the generic Artifact Registry hosting the final OS image tarballs."
}

variable "ar_package_name" {
  type        = string
  default     = "image-builder"
  description = "The package name under which the generic OS image artifact will be registered in Artifact Registry."
}

variable "trigger_name" {
  type        = string
  default     = "custom-os-image-builder"
  description = "The name of the Cloud Build trigger."
}

variable "cloudbuild_yaml_path" {
  type        = string
  default     = "cloudbuild.yaml"
  description = "The path to the cloudbuild.yaml configuration file relative to the repository root."
}

variable "image_builder_config_path" {
  type        = string
  default     = "imagebuilder.yaml"
  description = "The path to the imagebuilder.yaml configuration file relative to the repository root."
}

  3. Untuk men-deploy konfigurasi, jalankan perintah berikut di direktori yang berisi file Terraform Anda:

    1. Lakukan inisialisasi direktori: 
      terraform init
    2. Validasi sintaksis: 
      terraform validate
    3. Lihat pratinjau deployment: 
      terraform plan
    4. Terapkan konfigurasi: 
      terraform apply

Memverifikasi dan memantau build

Untuk melacak progres pipeline build, selesaikan langkah-langkah berikut:

  1. Di Google Cloud konsol, buka halaman Cloud Build.

    Buka Cloud Build

  2. Di menu navigasi, klik Histori untuk melihat tugas yang aktif atau selesai.

  3. Di daftar Build, klik ID Build build Anda untuk memeriksa log eksekusi container. Log menampilkan langkah-langkah yang dilakukan di dalam VM pekerja seperti update paket sistem atau perintah shell kustom, diikuti dengan hasil pengujian validasi dari VM pengujian, dan pendaftaran output akhir.

Langkah berikutnya