Azioni di personalizzazione supportate

Per personalizzare le immagini delle macchine virtuali, ad esempio eseguendo script del terminale, aggiornando i parametri di avvio, trasferendo i file binari o installando i driver GPU, puoi definire azioni helper 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 blocco name, un blocco action e un blocco inputs personalizzati in base a quel tipo di azione. Image Builder supporta le seguenti azioni di personalizzazione:

• Shell: esegue script o comandi del terminale incorporati nel sistema operativo guest 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 spazi di lavoro locali alla VM.
• InstallGPU: scarica, compila e registra i driver della GPU NVIDIA.

Azione della shell

L'azione Shell ti consente di eseguire script del terminale incorporati o singoli comandi 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 shell multiriga non elaborati da eseguire.
• command (stringa): una singola stringa di comando di sistema o un percorso relativo a un file binario eseguibile.

Configurazioni di esempio

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

- 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

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

Comportamenti speciali

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

Audit di sicurezza

Per evitare che token sensibili, segreti 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 attivato il debug interattivo (debug: true). Al contrario, registra l'hash di integrità SHA-256 del payload dello script nei log di build. Questo hash fornisce una traccia di controllo immutabile di quale codice è stato eseguito sull'immagine.

Riavvii del sistema (codice di uscita 3010)

Alcune azioni della shell, come gli aggiornamenti delle patch del kernel o le modifiche alla partizione 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 lo spazio di lavoro e riprende automaticamente la pipeline al passaggio successivo della coda.

Esempio di riavvio:

L'esempio seguente mostra una configurazione del 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, obbligatorio): gli argomenti della riga di comando esatti per individuare, rimuovere o sostituire all'interno della configurazione del bootloader.
• newArguments (stringa, facoltativo): 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 proprietà oldArguments dalla riga di avvio.

Configurazioni di esempio

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

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

- 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 alle immagini a seconda del sistema operativo guest di origine:

Azione FileCopy

L'azione FileCopy copia file di configurazione, file binari o 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, obbligatorio): il percorso assoluto nel sistema operativo guest in cui viene creato il file.
• permissions (stringa, obbligatorio): la rappresentazione ottale delle autorizzazioni di configurazione della 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 del file all'interno della cartella del repository dello spazio di lavoro locale. Il path traversal che utilizza ../ è bloccato per motivi di sicurezza.

Configurazioni di esempio

Le seguenti schede mostrano configurazioni di passaggi di esempio per copiare un file da Cloud Storage rispetto alla copia dal tuo workspace locale:

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

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

Linee guida specifiche per il sistema operativo

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

Azione InstallGPU

Utilizza l'azione InstallGPU per creare immagini VM ottimizzate per il machine learning, la data science o i carichi di lavoro scientifici. Image Builder scarica, compila e registra i driver GPU NVIDIA sulle tue 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 di driver personalizzati.

Specifica uno dei seguenti input in steps.inputs:

• version (stringa): il numero di 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 di un file .run di installazione all'interno della cartella del repository del workspace locale.

Configurazioni di esempio

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

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

- 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"

- 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 configurare i driver della GPU NVIDIA nelle immagini personalizzate:

Passaggi successivi

• Esamina i blocchi dello schema di primo livello nello schema del file di personalizzazione delle immagini.
• Configura i parametri di orchestrazione della pipeline nello schema del file di configurazione di Cloud Build.
• Segui il tutorial per creare una pipeline Image Builder.