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 di 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
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)

Metadati

Fornisce i dettagli identificativi per questo modello di build personalizzato:

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (stringa, obbligatorio): l'identificatore per 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: nvidia-l4
  acceleratorCount: 1
  debug: false
  instanceDurationHours: 2.0
  reservations:
    - RESERVATION_NAME
  • machineType (stringa, obbligatorio): il tipo di macchina Compute Engine da utilizzare per le VM di worker e di test. 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 worker e di test, ad esempio us-central1-a.
  • network (stringa, facoltativo): la rete VPC a cui collegare le VM di worker e di test di convalida, 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 a cui collegare le VM di worker e di test di convalida, 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 worker e di test di convalida. Valori consentiti:
    • ephemeral (valore predefinito): alloca un indirizzo IPv4 pubblico temporaneo da un pool condiviso.
    • none: crea VM senza indirizzo IP esterno, che utilizza solo la rete VPC privata. 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 di pacchetti richiesti Google Cloud .
  • 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 completamento o dall'esito negativo della personalizzazione, in modo che tu possa ispezionare o risolvere i problemi dell'istanza attiva utilizzando SSH. Il valore predefinito è false.
  • instanceDurationHours (numero, facoltativo): limita il tempo di esecuzione 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 interattive. Il limite massimo è di 2.0 ore.
  • reservations (array di stringhe, facoltativo): i nomi delle risorse di prenotazione della capacità (ad esempio test-reservation nello stesso progetto) da utilizzare quando Image Builder crea le VM.

Immagine di origine

Identifica l'immagine del sistema operativo 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 di rilascio 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:
        - us-central1
  • 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 Google Cloud progetto in cui Image Builder scrive l'immagine di output.
  • description (stringa, facoltativo): il testo della descrizione allegato ai metadati dell'immagine generata.
  • licenses (array di stringhe, facoltativo): i percorsi delle risorse delle licenze software specifiche applicate a questa immagine.
  • labels (mappa, facoltativo): le coppie chiave-valore dei metadati di tagging, ad esempio env: production.
  • signatureDatabaseFile (stringa, facoltativo): il percorso della risorsa di un file di database delle firme di avvio protetto.
  • storageLocations (array di stringhe, facoltativo): la regione di archiviazione di destinazione o la regione a più regioni, 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): indica se la VM di test valuta le condizioni di avvio, la rete e le strutture UEFI. Il valore predefinito è false.

Passaggi delle specifiche

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

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

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (stringa, obbligatorio): il nome definito dall'utente per questo passaggio di personalizzazione.
  • action (stringa, obbligatorio): l'azione helper da richiamare. Azioni supportate:
    • Shell: esegue gli script del terminale nella VM.
    • FileCopy: trasferisce le risorse dai bucket o dagli spazi di lavoro Cloud Storage.
    • UpdateKernelCommandLine: aggiorna i parametri di avvio.
    • InstallGPU: registra i driver della GPU NVIDIA.
  • inputs (oggetto, obbligatorio): le proprietà chiave-valore richieste dall'azione selezionata. Per riferimenti e 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