File di personalizzazione dell'immagine

Questo documento descrive la struttura e i parametri del file di ricetta di personalizzazione imagebuilder.yaml, che utilizzi per definire l'immagine del sistema operativo di base, le configurazioni hardware, le destinazioni di rilascio e le azioni di personalizzazione per la pipeline di Image Builder.

Panoramica dello schema

La configurazione della personalizzazione utilizza la versione API imagebuilder.gcp.com/v1 e il tipo di risorsa OSImageCustomization.

Un file di ricetta standard ha la seguente struttura:

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

Metadati

Fornisce i dettagli identificativi per questo modello di build personalizzato:

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (stringa, obbligatorio): l'identificatore di questa configurazione.
  • description (stringa, facoltativo): una descrizione dello scopo della build.

Configurazione dell'infrastruttura

Specifica le proprietà hardware e di rete delle istanze di macchine virtuali temporanee che Image Builder crea durante le attività di build e convalida:

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 (stringa, obbligatorio): il tipo di macchina Compute Engine da utilizzare per le VM di test e worker. Assicurati che il tipo di macchina corrisponda all'architettura dell'immagine di origine specificata in imageFamily o imagePath. Ad esempio, utilizza e2-standard-4 per le immagini x86 e c4a-standard-4 per le immagini Arm. I tipi di macchine bare metal non sono supportati.
  • zone (stringa, obbligatorio): la zona in cui vengono eseguite le VM di test e worker, ad esempio us-central1-a.
  • network (stringa, facoltativo): la rete VPC da collegare alle VM di test di convalida e worker, ad esempio projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> o default. Se omesso, Image Builder utilizza la rete predefinita.
  • subnetwork (stringa, facoltativo): la subnet VPC da collegare alle VM di test di convalida e worker, ad esempio projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>.
  • externalIP (stringa, facoltativo): specifica l'allocazione dell'indirizzo IP esterno per le VM di test di worker e convalida. Valori consentiti:
    • ephemeral (impostazione predefinita): alloca un indirizzo IPv4 temporaneo pubblico da un pool condiviso.
    • none: crea VM senza indirizzo IP esterno, che utilizza solo il networking VPC privato. Se impostato su none, assicurati che la subnet VPC abbia l'accesso privato Google o Cloud NAT abilitato in modo che le VM possano accedere ai servizi e ai repository dei pacchetti Cloud de Confiance richiesti.
  • acceleratorType (stringa, facoltativo): il tipo di acceleratore GPU da collegare alla VM worker, ad esempio nvidia-tesla-t4 o nvidia-l4.
  • acceleratorCount (numero, facoltativo): il numero di acceleratori GPU da collegare alla VM worker.
  • debug (booleano, facoltativo): se imposti debug su true, Image Builder conserva la VM worker indipendentemente dal fatto che la personalizzazione venga completata o non riesca, in modo da poter ispezionare o risolvere i problemi dell'istanza attiva utilizzando SSH. Il valore predefinito è false.
  • instanceDurationHours (numero, facoltativo): limita il runtime della VM worker. Il limite di tempo inizia quando la personalizzazione viene completata o si verifica un errore di script, consentendoti di connetterti alla VM attiva durante le sessioni di debug interattivo. Il limite massimo è di 2.0 ore.
  • reservations (array di stringhe, facoltativo): nomi delle risorse di prenotazione della capacità (ad esempio test-reservation nello stesso progetto) da utilizzare quando Image Builder crea le VM.
  • validationConcurrency (numero, facoltativo): specifica il numero massimo di test di convalida da eseguire in parallelo sull'istanza di computing temporanea del test di convalida. I valori consentiti includono:
    • 0 o omesso (impostazione predefinita): Image Builder rileva automaticamente la concorrenza in base al tipo di macchina e alla configurazione dell'acceleratore e la imposta come segue:
      • 1 (sequenziale) per tipi di macchine o configurazioni bare metal con acceleratori GPU collegati, il che contribuisce a evitare il superamento dei limiti di quota o l'esaurimento delle risorse.
      • 4 (parallelo) per tutti gli altri tipi di macchine.
    • 1: esegue i test di convalida in sequenza. Se il tuo progetto ha una quota limitata per machineType specificato, impostare la concorrenza su 1 può essere utile perché impedisce l'avvio di più istanze di calcolo contemporaneamente.
    • 2 o superiore: esegue il numero specificato di test di convalida in parallelo. Se disponi di capacità o prenotazioni sufficienti, l'aumento della concorrenza può ridurre il tempo di esecuzione complessivo dei test di convalida.

Immagine di origine

Identifica l'immagine di sistema di base che Image Builder utilizza per avviare la VM worker. Devi specificare una delle seguenti opzioni:

Per specificare una famiglia di immagini standard:

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

Per specificare un URI di versione dell'immagine diretta:

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily (stringa): il percorso di un gruppo Famiglia di immagini standard, ad esempio projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts.
  • imagePath (stringa): l'URI della risorsa diretta a una versione specifica dell'immagine Compute Engine, ad esempio projects/cos-cloud/global/images/cos-105-17412-226-28.

Destinazioni

Definisce dove e come rilasciare l'immagine del sistema operativo personalizzata compilata. Questa proprietà contiene un elenco di oggetti di destinazione della release in 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 (stringa, obbligatorio): il prefisso del nome di base assegnato alla risorsa immagine Compute Engine finale. Image Builder aggiunge automaticamente l'ID build univoco a questo prefisso e tronca il nome dell'immagine finale a 63 caratteri.
  • family (stringa, facoltativo): la famiglia di immagini da applicare all'immagine appena generata.
  • project (stringa, obbligatorio): il progetto Cloud de Confiance in cui Image Builder scrive l'immagine di output.
  • description (stringa, facoltativo): testo della descrizione allegato ai metadati dell'immagine generata.
  • licenses (array di stringhe, facoltativo): percorsi delle risorse di licenze software specifiche applicate a questa immagine.
  • labels (mappa, facoltativo): coppie chiave-valore dei metadati di tagging, ad esempio env: production.
  • signatureDatabaseFile (stringa, facoltativo): percorso della risorsa a un file di database della firma di avvio protetto.
  • storageLocations (array di stringhe, facoltativo): la regione o la regione multiregionale di archiviazione di destinazione, ad esempio us-central1 o us, in cui Compute Engine archivia i blocchi del disco finali. Nota: anche se questa proprietà è formattata come un elenco, puoi specificare una sola località per destinazione immagine.

Configurazione delle specifiche

Applica le opzioni di esecuzione generali:

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (booleano, facoltativo): attiva/disattiva la valutazione delle condizioni di avvio, del networking e delle strutture UEFI da parte della VM di test. Il valore predefinito è false.

Passaggi per le specifiche

Specifica un elenco di oggetti di passaggio che Image Builder esegue in ordine sulla VM worker. Per schemi di parametri di input ed esempi di utilizzo completi per ogni tipo di passaggio, vedi Azioni di personalizzazione supportate.

Tutti gli oggetti del passaggio di personalizzazione condividono le seguenti proprietà comuni:

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (stringa, obbligatorio): nome definito dall'utente per questo passaggio di personalizzazione.
  • action (stringa, obbligatorio): l'azione helper da richiamare. Azioni supportate:
  • inputs (oggetto, obbligatorio): le proprietà chiave-valore richieste dall'azione selezionata. Per riferimenti ed esempi completi dei parametri, consulta Azioni di personalizzazione supportate.

Il seguente snippet mostra un passaggio di esempio che utilizza l'azione Shell:

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

Passaggi successivi