Benutzerdefinierte Betriebssystem-Image-Pipeline mit gcloud oder Terraform erstellen

Sie können eine Image Builder-Pipeline programmatisch mit der Google Cloud CLI oder Terraform konfigurieren und einreichen. Wenn Sie Ihre Pipeline programmatisch konfigurieren, können Sie Infrastruktureinstellungen, Basisbetriebssystem-Images, Anpassungsaktionen und Validierungstests in deklarativen Konfigurationsdateien definieren.

Hinweis

  • Führen Sie die Schritte zur Umgebungseinrichtung unter Umgebung vorbereiten aus.
  • Wenn Sie Ihre Pipeline mit Terraform bereitstellen oder Builds aus einem Repository automatisieren möchten, verbinden Sie Ihr GitHub-, GitLab- oder Bitbucket-Repository mit Cloud Build-Repositories (2nd gen) oder Developer Connect-Verbindungslinks.
  • Wenn Sie Terraform verwenden möchten, installieren Sie die Terraform CLI Version 1.3 oder höher.
  • Richten Sie die Authentifizierung ein, falls Sie dies noch nicht getan haben. Bei der Authentifizierung wird Ihre Identität für den Zugriff auf Google Cloud Dienste und APIs überprüft. Wenn Sie Code oder Beispiele aus einer lokalen Entwicklungsumgebung ausführen möchten, können Sie sich bei Compute Engine authentifizieren, indem Sie eine der folgenden Optionen auswählen:

    Wählen Sie den Tab für die Verwendung der Beispiele auf dieser Seite aus:

    gcloud

    1. Installieren Sie die Google Cloud CLI. Initialisieren Sie die Google Cloud CLI nach der Installation mit dem folgenden Befehl: 

      gcloud init

      Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  • Legen Sie eine Standardregion und -zone fest.

    • Terraform

    Wenn Sie die Terraform-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, installieren und initialisieren Sie die gcloud CLI und richten Sie dann die Standardanmeldedaten für Anwendungen mit Ihren Nutzeranmeldedaten ein.

    1. Installieren Sie die Google Cloud CLI.

    2. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

    3. Wenn Sie eine lokale Shell verwenden, erstellen Sie lokale Anmeldedaten zur Authentifizierung für Ihr Nutzerkonto: 

      gcloud auth application-default login

      Wenn Sie Cloud Shell verwenden, ist dies nicht erforderlich.

      Wenn ein Authentifizierungsfehler zurückgegeben wird und Sie einen externen Identitätsanbieter (IdP) verwenden, prüfen Sie, ob Sie sich mit Ihrer föderierten Identität in der gcloud CLI angemeldet haben.

    Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Einreichen von Pipelines zur Bildanpassung mit der Google Cloud CLI oder Terraform benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Konfigurationsdateien erstellen

Wenn Sie Ihre Pipeline mit der gcloud CLI oder Terraform konfigurieren möchten, erstellen Sie zwei Konfigurationsdateien:

  • imagebuilder.yaml: Definiert das Anpassungsrezept für das Image, einschließlich des Basisbetriebssystem-Images, der Einstellungen für die Worker-VM-Infrastruktur, der Details zur Zielimageausgabe und der sequenziellen Anpassungsschritte wie das Ausführen von Shell-Skripts, das Übertragen von Dateien oder das Ausführen von Neustarts.
  • cloudbuild.yaml: Orchestriert die Build-Prozessschritte in Cloud Build, einschließlich des Parsens, der Validierung, des Erstellens, des Testens und der Veröffentlichung des benutzerdefinierten Betriebssystem-Images.

Image-Konfigurationsdatei erstellen

Erstellen Sie eine Datei mit dem Namen imagebuilder.yaml in Ihrem lokalen Verzeichnis, um die Image-Konfiguration anzugeben. Eine vollständige Liste aller unterstützten Schemafelder und Anpassungsaktionen finden Sie unter Schema für Anpassungsrezept und Unterstützte Anpassungsaktionen.

Die folgende Beispiel-imagebuilder.yaml-Datei konfiguriert eine Pipeline, die ein angepasstes Ubuntu 22.04 LTS-Image mit einer e2-standard-4-Worker-VM in der angegebenen Region und Zone erstellt und ein Systempaket-Update ausführt.

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"

Ersetzen Sie die folgenden Platzhalterwerte:

  • PROJECT_ID: Ihre Projekt-ID.
  • REGION: Der Speicherort des Zielimages, z. B. us-east1 oder europe-west1. Folgende regionale und zonale Anforderungen müssen erfüllt sein:
    • Image Builder wird nur in Regionen unterstützt, in denen Cloud Build verfügbar ist.
    • Die Worker-VM-ZONE muss sich in der angegebenen REGION befinden.
    • Um die Netzwerklatenz zu minimieren und regionsübergreifende Gebühren für ausgehenden Traffic zu vermeiden, müssen sich die Zone der Worker-VM, der Cloud Storage-Staging-Bucket, das Artifact Registry-Repository und der Speicherort des Zielimages in derselben Region befinden.
  • ZONE: Eine Zone in der angegebenen REGION, z. B. us-east1-b oder europe-west1-b.

Orchestrator-Build-Datei erstellen

Erstellen Sie im selben Verzeichnis eine Datei mit dem Namen cloudbuild.yaml. Diese Datei ruft die Image Builder-Containerschritte auf, um das benutzerdefinierte Betriebssystem-Image zu erstellen, zu validieren und zu veröffentlichen.

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'

Ersetzen Sie die folgenden Platzhalterwerte:

  • STAGING_BUCKET_NAME: Ein vorhandener Cloud Storage-Bucket in Ihrem Projekt, der als temporärer Staging-Arbeitsbereich verwendet werden soll. Wenn Sie keinen Bucket haben, können Sie einen erstellen, indem Sie gcloud storage buckets create gs://STAGING_BUCKET_NAME ausführen. Wenn Sie Ihre Pipeline mit Terraform bereitstellen, wird dieser Bucket automatisch von Terraform erstellt.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.
  • REGION: Die Google Cloud Region für Ihr Artifact Registry-Repository, z. B. us-east1 oder europe-west1.
  • SERVICE_ACCOUNT_EMAIL: Die E-Mail-Adresse des Dienst kontos, das Sie mit den erforderlichen IAM-Berechtigungen konfiguriert haben.
  • REPOSITORY und PACKAGE: Das Zielrepository und der Paketname, die in Artifact Registry erstellt wurden. Informationen zum Einrichten der Artifact Registry finden Sie unter Artifact Registry konfigurieren.

Build-Pipeline erstellen und einreichen

Wenn Sie Ihre Pipeline zur Bildanpassung ausführen möchten, reichen Sie einen Build mit der gcloud CLI ein oder stellen Sie Ihre Pipeline mit Terraform bereit. Wählen Sie einen der folgenden Tabs aus:

gcloud

Wenn Sie Ihre Pipeline zur Bildanpassung bereitstellen und ausführen möchten, führen Sie im lokalen Terminal verzeichnis mit beiden Konfigurationsdateien den gcloud builds submit Befehl aus:

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID.
  • REGION: Die Google Cloud Region, in der der Job für die Pipeline zur Bildanpassung ausgeführt werden soll.
  • SERVICE_ACCOUNT_EMAIL: Die E-Mail-Adresse des Dienstkontos, das mit den erforderlichen IAM-Berechtigungen konfiguriert wurde.

Mit diesem Befehl wird Ihr Anpassungsarbeitsbereich hochgeladen, die Cloud Build-Ausführung registriert und die Orchestrierungscontainer gestartet.

Terraform

Mit Terraform können Sie die Infrastruktur bereitstellen, die zum automatischen Erstellen und Validieren angepasster Betriebssystem-Images erforderlich ist. Diese Terraform-Konfiguration führt die folgenden Aufgaben aus:

  • Erforderliche Google Cloud APIs aktivieren.
  • Erstellt einen dedizierten Cloud Storage-Bucket (workdir_bucket) zum Speichern temporärer Logs und Build-Artefakte.
  • Konfiguriert einen Cloud Build-Trigger (image_builder_trigger), der mit Ihrer Developer Connect-GitHub-Repository-Verbindung verknüpft ist.

Terraform-Konfigurationsdateien erstellen

Führen Sie die folgenden Schritte aus, um Ihre Pipeline-Infrastruktur mit Terraform zu organisieren und bereitzustellen:

  1. Erstellen Sie auf Ihrer lokalen Workstation oder in Ihrer CI/CD-Umgebung ein dediziertes Verzeichnis, das von Ihrem Anwendungs-Repository getrennt ist, und wechseln Sie zu diesem Verzeichnis:

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

  2. Erstellen Sie in diesem Verzeichnis die folgenden fünf Terraform-Konfigurationsdateien:

    • terraform.tfvars: Legt Werte für projektspezifische Variablen fest.
    • main.tf: Stellt Ressourcen in Ihrem Google Cloud Projekt bereit, einschließlich der Aktivierung der erforderlichen APIs, der Erstellung des Cloud Storage-Staging Buckets (workdir_bucket) und der Bereitstellung des Cloud Build-Triggers (image_builder_trigger).
    • outputs.tf: Definiert Ausgabewerte, die nach der Bereitstellung in Ihrem Terminal angezeigt werden, z. B. die Trigger-ID und den Namen des Staging-Buckets.
    • providers.tf: Gibt die erforderliche Terraform-Version (>= 1.3) an und konfiguriert den Google Cloud Provider (hashicorp/google).
    • variables.tf: Definiert Eingabevariablen, Standardwerte und Validierungsregeln für die Bereitstellung.

    Wählen Sie einen der folgenden Tabs aus, um die Konfiguration der einzelnen Dateien aufzurufen und in Ihr lokales Verzeichnis zu kopieren:

    terraform.tfvars

    In dieser Datei werden Parameterwerte für Ihre Umgebung für die deklarierten Variablen angegeben:

    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"

    Ersetzen Sie die folgenden Platzhalter für Ihre vorhandenen Ressourcen:

    • PROJECT_ID: Ihre vorhandene Google Cloud Projekt-ID.
    • SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse Ihres Build-Dienstkontos, das unter Dienstkonto für Image Builder konfigurierenkonfiguriert wurde.
    • LOCATION, CONNECTION, und REPO_NAME: Ihre Developer Connect -Hostregion, der Verbindungsname und der Repository-Link, die unter Repository verbinden konfiguriert wurden.
    • CLOUDBUILD_YAML_PATH: Der relative Pfad zu Ihrer cloudbuild.yaml-Datei in Ihrem lokalen Verzeichnis. Sie müssen cloudbuild.yaml nicht in Ihr Git-Repository einchecken.
    • RECIPE_PATH: Der relative Pfad zu Ihrer imagebuilder.yaml-Datei für das Anpassungsrezept, die in Ihr Git-Repository eingecheckt wurde.
    • REPOSITORY_NAME: Das vorhandene generische Artifact Registry-Repository, das unter Artifact Registry konfigurieren erstellt wurde.

    Ersetzen Sie die folgenden Platzhalter für die Ressourcen, die von Terraform erstellt werden:

    • REGION: die Zielregion, in der Terraform den Cloud Storage-Staging-Bucket und den Cloud Build-Trigger bereitstellt, z. B. us-central1. Google Cloud
    • TRIGGER_NAME: Der Name für den neuen Cloud Build-Repository-Trigger, der von Terraform erstellt wurde, z. B. git-push-os-builder.
    • LIFECYCLE_DAYS: Der Aufbewahrungszeitraum in Tagen, bevor Zwischenartefakte im Cloud Storage-Staging-Bucket, der von Terraform erstellt wurde, automatisch gelöscht werden, z. B. 30.
    • PACKAGE_NAME: der Name, den Sie für das Paket verwenden möchten, das in Ihrem Artifact Registry-Repository erstellt wurde. In diesem Paket werden veröffentlichte Betriebssystem-Image-Versionen gespeichert, z. B. ubuntu-custom.

    main.tf

    In dieser Datei werden die wichtigsten Infrastrukturressourcen und Datenquellen für die Bereitstellung deklariert:

    # 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

    In dieser Datei werden die Ausgabeartefakte definiert, die nach der Bereitstellung an Ihr Terminal zurückgegeben werden:

    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

    In dieser Datei werden die erforderlichen Terraform-Versions- und Regionseinstellungen konfiguriert:

    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

    In dieser Datei werden alle erforderlichen und optionalen Eingabevariablen und Validierungsregeln deklariert:

    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. Führen Sie die folgenden Befehle im Verzeichnis mit Ihren Terraform-Dateien aus, um die Konfigurationen bereitzustellen:

    1. Initialisieren Sie das Verzeichnis: 
      terraform init
    2. Überprüfen Sie die Syntax: 
      terraform validate
    3. Sehen Sie sich eine Vorschau der Bereitstellung an: 
      terraform plan
    4. Wenden Sie die Konfiguration an: 
      terraform apply

Build prüfen und beobachten

Führen Sie die folgenden Schritte aus, um den Fortschritt Ihrer Build-Pipeline zu verfolgen:

  1. Rufen Sie in der Google Cloud Console die Seite Cloud Build auf.

    Zu Cloud Build

  2. Klicken Sie im Navigationsmenü auf Verlauf, um aktive oder abgeschlossene Jobs aufzurufen.

  3. Klicken Sie in der Liste Builds auf die Build-ID Ihres Builds, um die Container-Ausführungsprotokolle zu prüfen. In den Logs werden die Schritte angezeigt, die in der Worker-VM ausgeführt werden, z. B. Systempaket-Updates oder benutzerdefinierte Shell-Befehle, gefolgt von den Validierungstestergebnissen der Test-VM und der Registrierung der endgültigen Ausgabe.

Nächste Schritte