Créer un pipeline d'images d'OS personnalisées de manière programmatique

gcloud

Pour déployer et exécuter votre pipeline de personnalisation d'image, exécutez la commande gcloud builds submit à partir du répertoire de votre terminal local contenant les deux fichiers de configuration :

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

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet Cloud de Confiance .
• REGION : région Cloud de Confiance dans laquelle exécuter votre job de pipeline de personnalisation d'image.
• SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service configuré avec les autorisations IAM requises.

Cette commande importe votre espace de travail de personnalisation, enregistre l'exécution Cloud Build et lance les conteneurs d'orchestration.

Terraform

Pour provisionner l'infrastructure requise pour créer et valider automatiquement des images d'OS personnalisées, vous pouvez utiliser Terraform. Cette configuration Terraform effectue les tâches suivantes :

• Active les API Cloud de Confiance requises.
• Crée un bucket Cloud Storage dédié (workdir_bucket) pour stocker les journaux temporaires et les artefacts de compilation.
• Configure un déclencheur de compilation Cloud Build (image_builder_trigger) associé à votre connexion au dépôt GitHub Developer Connect.

Créer vos fichiers de configuration Terraform

Pour organiser et déployer votre infrastructure de pipeline à l'aide de Terraform, procédez comme suit :

1. Créez un répertoire dédié sur votre poste de travail local ou dans votre environnement CI/CD, distinct du dépôt de votre application, puis accédez-y :

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

2. Dans ce répertoire, créez les cinq fichiers de configuration Terraform suivants :

   • terraform.tfvars : définit les valeurs des variables spécifiques au projet.
   • main.tf : provisionne des ressources dans votre projet Cloud de Confiance , y compris l'activation des API requises, la création du bucket de préproduction Cloud Storage (workdir_bucket) et le déploiement du déclencheur de compilation Cloud Build (image_builder_trigger).
   • outputs.tf : définit les valeurs de sortie affichées dans votre terminal après le déploiement, telles que l'ID du déclencheur et le nom du bucket de préproduction.
   • providers.tf : spécifie la version Terraform requise (>= 1.3) et configure le fournisseur Cloud de Confiance by S3NS (hashicorp/google).
   • variables.tf : définit les variables d'entrée, les valeurs par défaut et les règles de validation du déploiement.

   Sélectionnez l'un des onglets suivants pour afficher et copier la configuration de chaque fichier dans votre répertoire local :

   terraform.tfvars

   Ce fichier spécifie les valeurs des paramètres de votre environnement pour les variables déclarées :

   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"
   

   Remplacez les espaces réservés suivants pour vos ressources préexistantes :

   • PROJECT_ID : ID de votre projetCloud de Confiance by S3NS existant.
   • SERVICE_ACCOUNT_EMAIL : adresse e-mail de votre compte de service de compilation configuré dans Configurer le compte de service Image Builder.
   • LOCATION, CONNECTION et REPO_NAME : région hôte, nom de connexion et lien vers le dépôt Developer Connect configurés dans Connecter un dépôt.
   • CLOUDBUILD_YAML_PATH : chemin relatif à votre fichier cloudbuild.yaml dans votre répertoire local. Vous n'avez pas besoin d'intégrer cloudbuild.yaml dans votre dépôt Git.
   • RECIPE_PATH : chemin relatif à votre fichier de recette de personnalisation imagebuilder.yaml enregistré dans votre dépôt Git.
   • REPOSITORY_NAME : dépôt Artifact Registry générique existant créé dans Configurer Artifact Registry.

   Remplacez les espaces réservés suivants pour les ressources créées par Terraform :

   • REGION : région cible Cloud de Confianceoù Terraform provisionne le bucket de préproduction Cloud Storage et le déclencheur de compilation Cloud Build, par exemple us-central1.
   • TRIGGER_NAME : nom du nouveau déclencheur de dépôt Cloud Build créé par Terraform, par exemple git-push-os-builder.
   • LIFECYCLE_DAYS : durée de conservation en jours avant la suppression automatique des artefacts intermédiaires dans le bucket de préproduction Cloud Storage créé par Terraform, par exemple 30.
   • PACKAGE_NAME : nom que vous souhaitez que Terraform utilise pour le package créé dans votre dépôt Artifact Registry. Ce package stocke les versions d'images de l'OS publiées, par exemple ubuntu-custom.

   main.tf

   Ce fichier déclare les ressources d'infrastructure de base et les sources de données pour le déploiement :

   # 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

   Ce fichier définit les attributs de sortie renvoyés à votre terminal après le déploiement :

   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

   Ce fichier configure la version de Terraform requise et les paramètres de région :

   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

   Ce fichier déclare toutes les variables d'entrée obligatoires et facultatives, ainsi que les règles de validation :

   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. Pour déployer les configurations, exécutez les commandes suivantes dans le répertoire contenant vos fichiers Terraform :

   1. Initialisez le répertoire :

      terraform init

   2. Validez la syntaxe :

      terraform validate

   3. Affichez un aperçu du déploiement :

      terraform plan

   4. Appliquez la configuration :

      terraform apply

Go

Avant d'exécuter cet exemple, importez votre fichier de configuration imagebuilder.yaml dans votre bucket de préproduction Cloud Storage, par exemple gs://STAGING_BUCKET_NAME/imagebuilder.yaml.

Pour envoyer une compilation Cloud Build qui exécute le pipeline Image Builder à l'aide de la bibliothèque cliente Go de Cloud Build, utilisez l'exemple suivant :

import (
	"context"
	"encoding/json"
	"fmt"
	"io"

	"google.golang.org/api/cloudbuild/v1"
)

// submitBuild submits a Cloud Build build that uses Image Builder to
// customize, validate, and publish a VM image to Compute Engine and Artifact
// Registry.
//
// Before you run this sample, upload your imagebuilder.yaml configuration file
// to Cloud Storage, create a generic Artifact Registry repository, and create a
// service account to run the build.
func submitBuild(w io.Writer, projectID, gcsWorkdir, configPath, serviceAccount string) error {
	// projectID := "my-project-id"
	region := "us-central1"
	// gcsWorkdir := "gs://my-bucket/workdir/"
	// configPath := "gs://my-bucket/imagebuilder.yaml"
	repository := "vm-images"
	packageName := "custom-os-images"
	// serviceAccount := "image-builder@my-project-id.iam.gserviceaccount.com"

	ctx := context.Background()
	cbService, err := cloudbuild.NewService(ctx)
	if err != nil {
		return fmt.Errorf("cloudbuild.NewService: %w", err)
	}

	sa := fmt.Sprintf("projects/%s/serviceAccounts/%s", projectID, serviceAccount)
	req := &cloudbuild.Build{
		ServiceAccount: sa,
		// AutomapSubstitutions exposes these substitutions to every step as
		// environment variables. See
		// https://cloud.google.com/build/docs/configuring-builds/substitute-variable-values#mapping_substitutions_to_environment_variables
		Substitutions: map[string]string{
			"_GCS_WORKDIR":               gcsWorkdir,
			"_SERVICE_ACCOUNT":           sa,
			"_IMAGE_OUTPUT_PATH":         "image-builder/binaryOut",
			"_IMAGE_BUILDER_CONFIG_PATH": configPath,
			"_ARTIFACT_REGISTRY_RESOURCE_URI": fmt.Sprintf(
				"projects/%s/locations/%s/repositories/%s/packages/%s/versions/v${BUILD_ID}",
				projectID, region, repository, packageName,
			),
		},
		Steps: []*cloudbuild.BuildStep{
			{
				Id:     "imagebuilder-customize",
				Name:   "us-docker.pkg.dev/image-builder-official/release/builder:stable",
				Script: "#!/usr/bin/env bash\n/build",
				Results: []*cloudbuild.StepResult{
					{
						Name:            "base_image",
						AttestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions",
					},
					{Name: "image_builder_telemetry_metrics"},
				},
			},
			{
				Id:      "imagebuilder-validate",
				Name:    "us-docker.pkg.dev/image-builder-official/release/validator:stable",
				Script:  "#!/usr/bin/env bash\n/validate",
				Results: []*cloudbuild.StepResult{{Name: "image_builder_telemetry_metrics"}},
			},
			{
				Id:      "imagebuilder-publish",
				Name:    "us-docker.pkg.dev/image-builder-official/release/builder:stable",
				Script:  "#!/usr/bin/env bash\n/publish",
				Results: []*cloudbuild.StepResult{{Name: "image_builder_telemetry_metrics"}},
			},
		},
		Options: &cloudbuild.BuildOptions{
			AutomapSubstitutions:  true,
			DynamicSubstitutions:  true,
			RequestedVerifyOption: "VERIFIED",
			SubstitutionOption:    "ALLOW_LOOSE",
			// Builds that run as a user-specified service account must set a
			// logging option.
			Logging: "CLOUD_LOGGING_ONLY",
		},
		Artifacts: &cloudbuild.Artifacts{
			GenericArtifacts: []*cloudbuild.GenericArtifact{
				{
					Folder:       "${_IMAGE_OUTPUT_PATH}",
					RegistryPath: "${_ARTIFACT_REGISTRY_RESOURCE_URI}",
				},
			},
		},
		Timeout: "3600s",
	}

	parent := fmt.Sprintf("projects/%s/locations/%s", projectID, region)
	op, err := cbService.Projects.Locations.Builds.Create(parent, req).Context(ctx).Do()
	if err != nil {
		return fmt.Errorf("Builds.Create: %w", err)
	}

	// The operation metadata contains the build that was created.
	var metadata cloudbuild.BuildOperationMetadata
	if err := json.Unmarshal(op.Metadata, &metadata); err != nil {
		return fmt.Errorf("json.Unmarshal: %w", err)
	}
	fmt.Fprintf(w, "Build submitted. ID: %s\n", metadata.Build.Id)
	fmt.Fprintf(w, "Logs: %s\n", metadata.Build.LogUrl)
	return nil
}