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 OS de base, les configurations matérielles, les destinations de publication et les actions de personnalisation pour votre pipeline Image Builder.

Présentation du schéma

La configuration de la 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
  name: CONFIG_NAME
  description: DESCRIPTION
infrastructureConfig:
  # VM machine type, zone, and network settings
  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: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
source:
  # Base source image profile
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY
  # Alternatively, use a direct image version URI:
  # imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
destinations:
  # Output OS image release targets
  - 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:
        - STORAGE_LOCATION
spec:
  config:
    # Build options and validation test flags
    skipSystemTests: false
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters

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, facultatif) : 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 que 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: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
  • 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, facultatif) : 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 vous ne le spécifiez pas, Image Builder utilise le réseau par défaut.
  • subnetwork (chaîne, facultatif) : 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, facultatif) : spécifie l'allocation d'adresses IP externes pour les VM de test de validation et de nœud de calcul. 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. Si la valeur 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 Cloud de Confiance et aux dépôts de packages requis.
  • acceleratorType (chaîne, facultatif) : type d'accélérateur GPU à associer à la VM de nœud de calcul, tel que 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 se termine ou échoue. Vous pouvez ainsi inspecter ou résoudre les problèmes liés à l'instance active à 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 des sessions de débogage interactif. La durée est limitée à 2.0 heures maximum.
  • 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.
  • validationConcurrency (nombre, facultatif) : spécifie le nombre maximal de tests de validation à exécuter en parallèle sur l'instance de calcul temporaire du test de validation. Les valeurs autorisées sont les suivantes :
    • 0 ou omis (par défaut) : Image Builder détecte automatiquement le degré de simultanéité en fonction du type de machine et de la configuration de l'accélérateur, et le définit comme suit :
      • 1 (séquentiel) pour les types de machines ou les configurations bare metal avec des accélérateurs GPU associés, ce qui permet d'éviter de dépasser les limites de quota ou d'épuiser les ressources.
      • 4 (parallèle) pour tous les autres types de machines.
    • 1 : exécute les tests de validation de manière séquentielle. Si votre projet dispose d'un quota limité pour le machineType spécifié, il peut être utile de définir la simultanéité sur 1, car cela empêche le démarrage de plusieurs instances de calcul en même temps.
    • 2 ou version ultérieure : exécute le nombre spécifié de tests de validation en parallèle. Si vous disposez d'une capacité ou de réservations suffisantes, l'augmentation de la simultanéité peut réduire la durée d'exécution globale des tests de validation.

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 standards :

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 standards, tel que projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts.
  • imagePath (chaîne) : URI direct de la ressource vers une version spécifique d'image Compute Engine, 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 la version 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:
        - STORAGE_LOCATION
  • name (chaîne, obligatoire) : préfixe du 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, facultatif) : famille d'images à appliquer à l'image nouvellement générée.
  • project (chaîne, obligatoire) : projet Cloud de Confiance dans lequel Image Builder écrit l'image de sortie.
  • description (chaîne, facultatif) : texte descriptif 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 taggage, telles que env: production.
  • signatureDatabaseFile (chaîne, facultatif) : chemin d'accès à un fichier de base de données de signatures de démarrage sécurisé.
  • storageLocations (tableau de chaînes, facultatif) : région ou multirégion de stockage cible, telle 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 lieu par destination d'image.

Configuration des spécifications

Applique les 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 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 acceptées :
    • Shell : Exécute des scripts de terminal dans la VM.
    • FileCopy : transfère les composants depuis des buckets Cloud Storage ou des espaces de travail.
    • 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 exemples et des informations de référence complètes sur les paramètres, consultez Actions de personnalisation acceptées.

L'extrait 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..."

Étapes suivantes