Fichier de personnalisation d'image

Ce document décrit la structure et les paramètres du fichier de recette de personnalisation, imagebuilder.yaml, que vous utilisez pour définir l'image de l'OS de base, les configurations matérielles, les destinations de publication et les actions de personnalisation de votre pipeline Image Builder.

Présentation du schéma

La configuration de personnalisation utilise la version d'API imagebuilder.gcp.com/v1 et le type de ressource OSImageCustomization.

Un fichier de recette standard présente la structure suivante :

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
infrastructureConfig:
  # VM machine type, zone, and network settings
source:
  # Base source image profile
destinations:
  # Output OS image release targets
spec:
  config:
    # Build options and validation test flags
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)

Métadonnées

Fournit des informations d'identification pour ce modèle de compilation personnalisé :

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (chaîne, obligatoire) : identifiant de cette configuration.
  • description (chaîne, facultative) : description de l'objectif de la compilation.

Configuration de l'infrastructure

Spécifie les propriétés matérielles et réseau des instances de machines virtuelles temporaires qu'Image Builder crée lors des tâches de compilation et de validation :

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: nvidia-l4
  acceleratorCount: 1
  debug: false
  instanceDurationHours: 2.0
  reservations:
    - RESERVATION_NAME
  • machineType (chaîne, obligatoire) : type de machine Compute Engine à utiliser pour les VM de nœud de calcul et de test. Assurez-vous que le type de machine correspond à l'architecture de l'image source que vous spécifiez dans imageFamily ou imagePath. Par exemple, utilisez e2-standard-4 pour les images x86 et c4a-standard-4 pour les images Arm. Les types de machines bare metal ne sont pas compatibles.
  • zone (chaîne, obligatoire) : zone dans laquelle les VM de nœud de calcul et de test s'exécutent, par exemple us-central1-a.
  • network (chaîne, facultative) : réseau VPC à associer aux VM de nœud de calcul et de test de validation, par exemple projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> ou default. Si cette option est omise, Image Builder utilise le réseau par défaut.
  • subnetwork (chaîne, facultative) : sous-réseau VPC à associer aux VM de nœud de calcul et de test de validation, par exemple projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>.
  • externalIP (chaîne, facultative) : spécifie l'attribution d'adresses IP externes pour les VM de nœud de calcul et de test de validation. Valeurs autorisées :
    • ephemeral (par défaut) : attribue une adresse IPv4 publique éphémère à partir d'un pool partagé.
    • none: crée des VM sans adresse IP externe, qui n'utilisent que la mise en réseau VPC privée. Lorsque cette option est définie sur none, assurez-vous que l'accès privé à Google ou Cloud NAT est activé pour votre sous-réseau VPC afin que les VM puissent accéder aux services Google Cloud et aux dépôts de packages requis.
  • acceleratorType (chaîne, facultative) : type d'accélérateur GPU à associer à la VM de nœud de calcul, par exemple nvidia-tesla-t4 ou nvidia-l4.
  • acceleratorCount (nombre, facultatif) : nombre d'accélérateurs GPU à associer à la VM de nœud de calcul.
  • debug (booléen, facultatif) : si vous définissez debug sur true, Image Builder conserve la VM de nœud de calcul, que la personnalisation soit terminée ou non, afin que vous puissiez inspecter l'instance active ou résoudre les problèmes à l'aide de SSH. La valeur par défaut est false.
  • instanceDurationHours (nombre, facultatif) : limite la durée d'exécution de la VM de nœud de calcul. Le délai commence lorsque la personnalisation est terminée ou qu'une erreur de script se produit, ce qui vous permet de vous connecter à la VM active lors de sessions de débogage interactives. La limite maximale est de 2.0 heures.
  • reservations (tableau de chaînes, facultatif) : noms de ressources de réservation de capacité (tels que test-reservation dans le même projet) à utiliser lorsque Image Builder crée des VM.

Image source

Identifie l'image du système d'exploitation de base qu'Image Builder utilise pour lancer la VM de nœud de calcul. Vous devez spécifier l'une des options suivantes :

Pour spécifier une famille d'images standard :

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

Pour spécifier un URI de version d'image directe :

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily (chaîne) : chemin d'accès à un groupe de familles d'images standard, tel que projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts.
  • imagePath (chaîne) : URI de ressource directe vers une version d'image Compute Engine spécifique, telle que projects/cos-cloud/global/images/cos-105-17412-226-28.

Destinations

Définit où et comment publier l'image d'OS personnalisée compilée. Cette propriété contient une liste d'objets de destination de publication sous 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:
        - us-central1
  • name (chaîne, obligatoire) : préfixe de nom de base attribué à la ressource d'image Compute Engine finale. Image Builder ajoute automatiquement l'ID de compilation unique à ce préfixe et tronque le nom de l'image finale à 63 caractères.
  • family (chaîne, facultative) : famille d'images à appliquer à l'image nouvellement générée.
  • project (chaîne, obligatoire) : projet dans lequel Google Cloud Image Builder écrit l'image de sortie.
  • description (chaîne, facultative) : texte de description associé aux métadonnées de l'image générée.
  • licenses (tableau de chaînes, facultatif) : chemins d'accès aux ressources de licences logicielles spécifiques appliquées à cette image.
  • labels (map, facultatif) : paires clé/valeur de métadonnées de tag, telles que env: production.
  • signatureDatabaseFile (chaîne, facultative) : chemin d'accès à un fichier de base de données de signature de démarrage sécurisé.
  • storageLocations (tableau de chaînes, facultatif) : région ou emplacement multirégional de stockage cible, tel que us-central1 ou us, où Compute Engine stocke les blocs de disque finaux. Remarque : Bien que cette propriété soit mise en forme sous forme de liste, vous ne pouvez spécifier qu'un seul emplacement par destination d'image.

Configuration de la spécification

Applique des options d'exécution générales :

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (booléen, facultatif) : indique si la VM de test évalue les conditions de démarrage, la mise en réseau et les structures UEFI. La valeur par défaut est false.

Étapes de la spécification

Spécifie une liste d'objets d'étape qu'Image Builder exécute dans l'ordre sur la VM de nœud de calcul. Pour obtenir des schémas de paramètres d'entrée complets et des exemples d'utilisation pour chaque type d'étape, consultez Actions de personnalisation compatibles.

Tous les objets d'étape de personnalisation partagent les propriétés communes suivantes :

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (chaîne, obligatoire) : nom défini par l'utilisateur pour cette étape de personnalisation.
  • action (chaîne, obligatoire) : action d'assistance à appeler. Actions compatibles :
    • Shell: exécute des scripts de terminal dans la VM.
    • FileCopy: transfère des éléments depuis des buckets ou des espaces de travail Cloud Storage.
    • UpdateKernelCommandLine: met à jour les paramètres de démarrage.
    • InstallGPU: enregistre les pilotes de GPU NVIDIA.
  • inputs (objet, obligatoire) : propriétés clé/valeur requises par l'action sélectionnée. Pour obtenir des références et des exemples de paramètres complets, consultez Actions de personnalisation compatibles.

L'extrait de code suivant montre un exemple d'étape utilisant l'action Shell :

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

Étape suivante