Azioni di personalizzazione supportate

Per personalizzare le immagini delle macchine virtuali, ad esempio eseguendo script del terminale, aggiornando i parametri di avvio, trasferendo file binari o installando i driver GPU, puoi definire azioni di assistenza specifiche all'interno del blocco spec.steps della tua ricetta di personalizzazione (imagebuilder.yaml).

Panoramica

Durante la fase di esecuzione di una build di Image Builder, l'orchestratore esegue in sequenza i passaggi dichiarati nella ricetta di personalizzazione (spec.steps) sulla VM worker temporanea.

Ogni passaggio deve specificare un name, un action e un blocco inputs personalizzato per quel tipo di azione. Image Builder supporta le seguenti azioni di personalizzazione:

  • Shell: esegue script o comandi del terminale in linea sul sistema operativo guest del worker.
  • UpdateKernelCommandLine: modifica i parametri di avvio e i flag della riga di comando del kernel.
  • FileCopy: trasferisce file di configurazione, script o asset da Cloud Storage o dalle aree di lavoro locali alla VM.
  • InstallGPU: scarica, compila e registra i driver GPU NVIDIA.

Azione Shell

L'azione Shell consente di eseguire script del terminale in linea o singoli comandi della shell sul sistema operativo guest della VM worker temporanea per eseguire personalizzazioni come l'aggiornamento dei pacchetti, la configurazione degli account utente o la compilazione del software.

Specifica uno dei seguenti input in steps.inputs:

  • inlineScript (stringa): comandi della shell multiriga non elaborati da eseguire.
  • command (stringa): una singola stringa di comando di sistema o un percorso relativo a un file binario eseguibile.

Esempi di configurazione

Le seguenti schede mostrano esempi di configurazioni dei passaggi per l'esecuzione di uno script in linea rispetto all'esecuzione di un singolo comando:

Esegui uno script in linea

La seguente configurazione esegue uno script multiriga che aggiorna i pacchetti utilizzando apt:

- name: "Update guest packages and configure groups"
  action: Shell
  inputs:
    inlineScript: |
      #!/bin/bash
      apt-get update -y
      apt-get install -y fail2ban build-essential
      groupadd -r adminusers

Esegui un singolo comando

La seguente configurazione esegue un singolo comando della shell per verificare la versione kernel del sistema operativo attivo:

- name: "Log kernel identifier"
  action: Shell
  inputs:
    command: "uname -a"

Comportamenti speciali

Quando esegui le azioni Shell, il provisioner di personalizzazione gestisce l'audit di sicurezza e i riavvii automatici del sistema come descritto nelle sezioni seguenti:

Audit di sicurezza

Per evitare che token sensibili, secret o codice proprietario vengano divulgati nei log di esecuzione, il provisioner di personalizzazione non stampa le righe non elaborate degli script, a meno che non sia abilitato il debug interattivo (debug: true). Invece, registra l'hash di integrità SHA-256 del payload dello script nei log di build. Questo hash fornisce una traccia di audit immutabile del codice eseguito esattamente sull'immagine.

Riavvii del sistema (codice di uscita 3010)

Alcune azioni della shell, come gli aggiornamenti delle patch del kernel o le modifiche delle partizioni di archiviazione, richiedono un riavvio del sistema prima che possano essere eseguiti i passaggi successivi.

Per richiedere un riavvio del sistema durante la personalizzazione, lo script della shell deve terminare con il comando exit 3010. Quando il provisioner di personalizzazione riceve il codice di uscita 3010, gestisce il ciclo di vita del riavvio nel seguente modo:

  1. Il provisioner rileva il codice di uscita 3010, mette in pausa l'esecuzione e contrassegna l'indice di avanzamento del passaggio.
  2. Il provisioner riavvia la VM worker.
  3. Dopo il riavvio della VM, il provisioner monta l'area di lavoro e riprende automaticamente la pipeline al passaggio successivo nella coda.
Esempio di riavvio:

Il seguente esempio mostra una configurazione di passaggio che aggiorna i pacchetti e richiede un riavvio:

- name: "Install core updates and request reboot"
  action: Shell
  inputs:
    inlineScript: |
      #!/bin/bash
      echo "Applying configuration package upgrades..."
      apt-get dist-upgrade -y
      # Terminate with return code 3010 to trigger a system reboot
      exit 3010
- name: "Post-reboot verification"
  action: Shell
  inputs:
    command: "uname -r"

Azione UpdateKernelCommandLine

L'azione UpdateKernelCommandLine individua, sostituisce, inserisce o rimuove i flag della riga di comando passati al kernel all'avvio del sistema, ad esempio quando configuri i log della console o modifichi i parametri del kernel.

Specifica le seguenti proprietà nella mappa steps.inputs:

  • oldArguments (stringa, obbligatoria): gli argomenti della riga di comando esatti da individuare, rimuovere o sostituire all'interno della configurazione del bootloader.
  • newArguments (stringa, facoltativa): gli argomenti di sostituzione da scrivere al posto dei flag di destinazione. Se ometti la proprietà newArguments, Image Builder rimuove completamente i parametri configurati nella oldArguments proprietà dalla riga di avvio.

Esempi di configurazione

Le seguenti schede mostrano esempi di configurazioni dei passaggi per la sostituzione o la rimozione degli argomenti di avvio del kernel:

Sostituisci gli argomenti di avvio

La seguente configurazione individua la chiave del livello di log del kernel loglevel=4 e la sostituisce con parametri più dettagliati loglevel=6 console=ttyS0:

- name: "Configure detailed boot logging"
  action: UpdateKernelCommandLine
  inputs:
    oldArguments: "loglevel=4"
    newArguments: "loglevel=6 console=ttyS0"

Rimuovi gli argomenti di avvio

La seguente configurazione cerca il parametro quiet e lo rimuove dagli argomenti di avvio per abilitare la registrazione dettagliata durante le fasi di controllo dell'avvio:

- name: "Enable verbose startup diagnostics"
  action: UpdateKernelCommandLine
  inputs:
    oldArguments: "quiet"

Dettagli di esecuzione specifici del sistema operativo

Le seguenti schede descrivono come il provisioner di personalizzazione gestisce le modifiche delle immagini a seconda del sistema operativo guest di origine:

Container-Optimized OS (COS)

Poiché COS presenta un layout di partizione di sola lettura, omette gli strumenti di configurazione standard. Il provisioner di personalizzazione esegue le seguenti operazioni:

  1. Determina il percorso del dispositivo di avvio attivo.
  2. Monta la partizione 12, la partizione EFI, del dispositivo di avvio.
  3. Aggiorna direttamente i parametri del bootloader all'interno di /efi/boot/grub.cfg.
  4. Smonta in modo sicuro la partizione 12.

Ubuntu

Nelle immagini Ubuntu, il provisioner di personalizzazione esegue le seguenti operazioni:

  1. Apre /etc/default/grub e i file in /etc/default/grub.d/*.cfg.
  2. Inserisce, modifica o elimina gli argomenti di destinazione nel blocco GRUB_CMDLINE_LINUX.
  3. Esegue il comando del pacchetto update-grub per rigenerare le configurazioni del bootloader.

Azione FileCopy

L'azione FileCopy copia i file di configurazione, i file binari o i certificati da un bucket remoto o dal repository locale all'immagine personalizzata. Il provisioner di personalizzazione scarica o legge il file di origine, lo scrive nel percorso guest specificato nella VM worker e configura le autorizzazioni.

Specifica i seguenti input in steps.inputs:

  • destination (stringa, obbligatoria): il percorso assoluto nel sistema operativo guest in cui viene creato il file.
  • permissions (stringa, obbligatoria): la rappresentazione ottale delle autorizzazioni di configurazione di destinazione, ad esempio "0755" o "0644".
  • Specifica una delle seguenti proprietà di origine:
    • gcsSourcePath (stringa): l'URI Cloud Storage del file di origine, che deve seguire il formato gs://BUCKET_NAME/OBJECT_NAME.
    • localSourcePath (stringa): il percorso relativo al file all'interno della cartella del repository dell'area di lavoro locale. L'attraversamento del percorso utilizzando ../ è bloccato per motivi di sicurezza.

Esempi di configurazione

Le seguenti schede mostrano esempi di configurazioni dei passaggi per la copia di un file da Cloud Storage rispetto alla copia dall'area di lavoro locale:

Cloud Storage

La seguente configurazione copia un modello di configurazione da un bucket Cloud Storage all'immagine della VM guest:

- name: "Import licensing configuration"
  action: FileCopy
  inputs:
    gcsSourcePath: "gs://enterprise-configs-bucket/licensing/license.key"
    destination: "/etc/app/license.key"
    permissions: "0600"

Area di lavoro locale

La seguente configurazione copia uno script dell'applicazione compilato durante i passaggi precedenti di Cloud Build:

- name: "Deploy setup automation daemon"
  action: FileCopy
  inputs:
    localSourcePath: "bin/setup-daemon"
    destination: "/usr/local/bin/setup-daemon"
    permissions: "0755"

Linee guida specifiche del sistema operativo

Le seguenti schede descrivono le linee guida per la posizione dei file a seconda del sistema operativo guest di destinazione:

Container-Optimized OS (COS)

Le immagini COS contengono un layout di partizione di sola lettura per motivi di sicurezza. Alcune destinazioni di sistema standard, come /usr/ o /bin/, sono protette dalla scrittura.

Quando configuri le destinazioni dei file in COS:

  • Specifica i file solo all'interno di posizioni stateful scrivibili, come /var o /home.
  • Fai riferimento alla documentazione ufficiale di Container-Optimized OS Disks and file system per identificare i percorsi appropriati.

Ubuntu

Le immagini Ubuntu presentano un layout di partizione principale di lettura/scrittura Linux standard (/). Puoi specificare le destinazioni dei file all'interno di qualsiasi percorso di sistema standard, come /etc, /usr/local/bin, /var, o /home, a condizione che il profilo utente o la cartella di destinazione disponga delle autorizzazioni di configurazione appropriate nella VM worker.

Azione InstallGPU

Utilizza l'azione InstallGPU per creare immagini VM ottimizzate per il machine learning, la data science o i workload scientifici. Image Builder scarica, compila e registra i driver GPU NVIDIA sulle immagini personalizzate. A seconda del tipo di immagine di base e dell'hardware di destinazione, puoi scegliere tra l'installazione di driver precompilati o la compilazione di file .run dei driver personalizzati.

Specifica uno dei seguenti input in steps.inputs:

  • version (stringa): il numero della versione del driver NVIDIA di destinazione, ad esempio "595.129.03". Se specifichi solo version, l'orchestratore scarica il driver dal repository NVIDIA ufficiale (https://us.download.nvidia.com/tesla/<version>).
  • gcsRunfile (stringa): il percorso Cloud Storage di un file di installazione del driver NVIDIA personalizzato, che deve utilizzare il formato gs://BUCKET_NAME/OBJECT_NAME.run.
  • sourceRunfile (stringa): il percorso relativo a un file .run di installazione all'interno della cartella del repository dell'area di lavoro locale.

Esempi di configurazione

Le seguenti schede mostrano esempi di configurazioni dei passaggi per l'installazione di una versione specifica del driver precompilato rispetto all'installazione di un file eseguibile personalizzato:

Download della versione standard

La seguente configurazione scarica e installa una versione specifica del driver NVIDIA dal repository ufficiale:

- name: "Configure default NVIDIA drivers"
  action: InstallGPU
  inputs:
    version: "<var>DRIVER_VERSION</var>"

File eseguibile Cloud Storage

La seguente configurazione esegue il deployment di un programma di installazione .run del driver NVIDIA personalizzato direttamente da un bucket Cloud Storage:

- name: "Deploy custom GPU driver from Cloud Storage"
  action: InstallGPU
  inputs:
    gcsRunfile: "gs://<var>BUCKET_NAME</var>/drivers/NVIDIA-Linux-aarch64-<var>DRIVER_VERSION</var>.run"

File eseguibile dell'area di lavoro locale

La seguente configurazione esegue il deployment di un programma di installazione .run del driver NVIDIA personalizzato dall'area di lavoro del repository locale:

- name: "Deploy custom GPU driver from workspace"
  action: InstallGPU
  inputs:
    sourceRunfile: "drivers/NVIDIA-Linux-x86_64-<var>DRIVER_VERSION</var>.run"

Metodi di configurazione

Le seguenti schede descrivono i metodi supportati per la configurazione dei driver GPU NVIDIA sulle immagini personalizzate:

Driver precompilati

Ti consigliamo di utilizzare le versioni dei driver precompilate per evitare il sovraccarico di calcolo e il tempo di compilazione dei driver da zero.

  • Container-Optimized OS (COS): se specifichi una versione del driver precompilata da Google, il provisioner di personalizzazione esegue lo strumento guest cos-extensions install gpu per attivarlo.

    Per visualizzare l'elenco delle versioni dei driver precompilate supportate per la release di COS, esegui sudo cos-extensions list su un'istanza COS in esecuzione, o consulta Identificare la versione del driver GPU.

  • Ubuntu: per ridurre il tempo di compilazione su Ubuntu, ti consigliamo di selezionare immagini di base preconfigurate dal progetto pubblico ubuntu-os-accelerator-images in cui sono preinstallati i driver NVIDIA.

    Per elencare le immagini dell'acceleratore disponibili, esegui il seguente comando in gcloud CLI:

    gcloud compute images list \
    --project=ubuntu-os-accelerator-images \
    --no-standard-images

File eseguibili personalizzati

Se devi installare una versione del driver personalizzata non precompilata da Google o Canonical, puoi specificare i file eseguibili di installazione diretti per la compilazione nel seguente modo:

  • Ubuntu: esegue la compilazione in-guest. Il provisioner di personalizzazione installa automaticamente le intestazioni del kernel corrispondenti (linux-headers-$(uname -r)), compila il file .run del driver NVIDIA sulla VM worker e lo registra con Dynamic Kernel Module Support (DKMS). La registrazione con DKMS garantisce che i driver rimangano attivi durante gli aggiornamenti del kernel secondari.
  • Container-Optimized OS (COS): il comportamento di compilazione varia a seconda dell'architettura della CPU dell'immagine VM di base di origine:
    • Immagini ARM64: poiché le VM COS ARM64 non supportano la compilazione delle intestazioni in-guest, Image Builder compila automaticamente in modo incrociato l'utilità del driver personalizzato .run all'interno del container di build e installa il bundle risultante in /var/lib/nvidia sulla VM worker.
    • Immagini x86-64: esegue la compilazione in-guest direttamente sulla VM worker.

Passaggi successivi