Risolvere i problemi relativi agli errori della pipeline

Linux

Nota:Image Builder è disponibile a livello generale, ma il tuo progetto deve essere aggiunto a una lista consentita prima di poterlo utilizzare. Per richiedere l'accesso, invia il modulo di richiesta di accesso o contatta il team dedicato al tuo account Google Cloud. La lista consentita copre solo i service account del tuo progetto e non quelli di proprietà di Google. Per saperne di più, consulta Service account inclusi nella lista consentita.

Se la pipeline Image Builder non va a buon fine durante la fase di personalizzazione, esamina i file di log, configura il flag di debug interattivo sulla VM worker o analizza le immagini di debug intermedie per identificare errori di compilazione o di script.

Prima di iniziare

• Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione verifica la tua identità per l'accesso ad API e servizi Google Cloud . Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:

  1. Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente:

     gcloud init

     Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

     Nota:se hai installato gcloud CLI in precedenza, assicurati di avere l'ultima versione eseguendo gcloud components update.
  2. Imposta una regione e una zona predefinite.

Esaminare i canali di logging

Image Builder scrive i log in più posizioni per aiutarti a diagnosticare gli errori a diversi livelli dello stack:

• Log dell'orchestratore Cloud Build: mostra i passaggi di creazione di alto livello nella console Cloud Build. Se un passaggio non va a buon fine, viene stampato un link alla directory workdir di Cloud Storage corrispondente.
• Log dell'agente VM di personalizzazione: l'agente di personalizzazione acquisisce l'output standard (stdout) e l'errore standard (stderr) dei passaggi di personalizzazione. L'orchestratore esegue il polling di questi record e li trasmette in streaming direttamente nei log di traccia di Cloud Build. Se i log sono troncati o devi esaminarli per intero, vai alla cartella corrispondente all'ID build nel bucket _GCS_WORKDIR.
• Log della console seriale: se il sistema operativo guest non si avvia, l'agente di personalizzazione non può avviarsi. In questi casi, esamina i log della console seriale. L'orchestratore trasmette l'output della porta seriale della VM worker direttamente al bucket workdir di Cloud Storage. Un link al file di log seriale viene stampato alla fine della traccia di Cloud Build non riuscita.
• Log del journal del sistema operativo guest: per la risoluzione dei problemi dettagliata a livello di sistema su Linux, l'agente di personalizzazione carica una copia completa del log journal nel bucket workdir di Cloud Storage al termine dell'esecuzione.

Risolvere gli errori degli script utilizzando il flag di debug

Per impostazione predefinita, se un passaggio di personalizzazione non va a buon fine, Image Builder termina l'esecuzione ed elimina immediatamente la VM worker per controllare i costi.

Per eseguire il debug degli script in modo interattivo, puoi attivare il flag debug. In questo modo la VM rimane attiva, consentendoti di connetterti direttamente al sistema guest attivo utilizzando SSH.

Attivare il flag di debug

Nel file imagebuilder.yaml, imposta debug: true nel blocco infrastructureConfig:

infrastructureConfig:
  machineType: e2-standard-4
  zone: us-central1-a
  # Enable interactive debugging
  debug: true
  instanceDurationHours: 1.5

Attiva la build e attendi l'errore

Invia la build utilizzando i metodi standard. Se la pipeline rileva un errore di script, si verifica quanto segue:

1. L'orchestratore mette in pausa l'esecuzione della build.
2. Image Builder non elimina la VM worker. Continua a essere eseguito nel tuo progetto.
3. La VM rimane attiva per il periodo di tempo specificato nella proprietà instanceDurationHours prima dell'interruzione automatica.

Connettiti alla VM worker per il debug

Esamina l'output della console Cloud Build per recuperare il nome dell'istanza VM worker attiva. Apri un terminale e connettiti alla VM worker utilizzando gcloud compute ssh:

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID

Se il file imagebuilder.yaml configura externalIP: none, il che comporta l'assenza di un indirizzo IP esterno, includi il flag --tunnel-through-iap per connetterti utilizzando l'inoltro TCP di Identity-Aware Proxy (IAP):

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID \
    --tunnel-through-iap

Una volta connesso, puoi eseguire comandi in tempo reale, esaminare i file di destinazione, analizzare i processi in esecuzione, rivedere i log della cronologia del programma di installazione e testare le modifiche agli script per il test direttamente sul disco.

Analizzare le immagini di debug intermedie

In alternativa a mantenere attiva la VM worker con il flag debug, puoi analizzare lo stato del disco utilizzando l'immagine di debug generata automaticamente:

1. Ogni volta che una build non va a buon fine con debug: false (il valore predefinito), l'orchestratore esporta il disco di avvio personalizzato parzialmente come immagine Compute Engine.
2. L'immagine di debug viene denominata utilizzando il pattern image-builder-debug-image-BUILD_ID e viene assegnata alla famiglia di immagini image-builder-debug-images.

3. Per esaminare il file system, crea un'istanza VM temporanea utilizzando questa immagine di debug come disco di avvio:

   gcloud compute instances create temp-debug-vm \
       --image-family=image-builder-debug-images \
       --zone=ZONE \
       --project=PROJECT_ID
   

4. Connettiti all'istanza temp-debug-vm per ispezionare il disco e capire perché la personalizzazione non è riuscita.

Risolvi i timeout di Cloud Build

Se l'esecuzione di una pipeline Image Builder richiede più tempo del previsto, il job Cloud Build si arresta e non va a buon fine con lo stato TIMEOUT.

I tempi di compilazione possono variare e in genere sono più lunghi per i tipi di macchina più grandi, quindi imposta il timeout in modo da concedere più tempo per il completamento della compilazione. Se non impostato, il timeout predefinito di Cloud Build è di 1 ora (3600s).

Per configurare un timeout più lungo, imposta il campo timeout a livello di root del file cloudbuild.yaml:

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

# Increase the overall build timeout (for example, 2 hours)
timeout: '7200s'

Dopo aver aggiornato il valore di timeout, esegui di nuovo la build e verifica che la pipeline Image Builder possa essere eseguita fino al completamento.

Per saperne di più sul parametro timeout, consulta timeout nella documentazione di Cloud Build.