Fehler bei Pipelines beheben

Wenn Ihre Image Builder-Pipeline während der Anpassungsphase fehlschlägt, prüfen Sie die Logdateien, konfigurieren Sie das interaktive Debugging-Flag auf Ihrer Worker-VM oder analysieren Sie Zwischen-Debugging-Images, um Kompilierungs- oder Skriptfehler zu ermitteln.

Hinweis

Logging-Channels prüfen

Image Builder schreibt Protokolle an mehrere Speicherorte, damit Sie Fehler auf verschiedenen Ebenen des Stacks diagnostizieren können:

  • Cloud Build-Orchestrator-Logs: Hier werden die Builder-Schritte auf hoher Ebene in der Cloud Build Console angezeigt. Wenn ein Schritt fehlschlägt, wird ein Link zum entsprechenden Cloud Storage-Arbeitsverzeichnis ausgegeben.
  • Logs des Anpassungs-VM-Agents: Der Anpassungs-Agent erfasst die Standardausgabe (stdout) und den Standardfehler (stderr) Ihrer Anpassungsschritte. Der Orchestrator fragt diese Datensätze ab und streamt sie direkt in die Cloud Build-Tracelogs. Wenn die Logs abgeschnitten sind oder Sie sie vollständig ansehen möchten, rufen Sie den Ordner mit Ihrer Build-ID im _GCS_WORKDIR-Bucket auf.
  • Logs der seriellen Konsole: Wenn das Gastbetriebssystem nicht gestartet werden kann, kann der Anpassungs-Agent nicht gestartet werden. Sehen Sie sich in diesen Fällen die Logs der seriellen Konsole an. Der Orchestrator streamt die Ausgabe des seriellen Ports der Worker-VM direkt in Ihren Cloud Storage-Arbeitsverzeichnis-Bucket. Am Ende des fehlgeschlagenen Cloud Build-Traces wird ein Link zur seriellen Logdatei ausgegeben.
  • Gastbetriebssystem-Journalprotokolle: Für die detaillierte Fehlerbehebung auf Systemebene unter Linux lädt der Anpassungs-Agent am Ende des Laufs eine vollständige Kopie des journal-Systemprotokolls in Ihren Cloud Storage-Arbeitsverzeichnis-Bucket hoch.

Scriptfehler mit dem Debug-Flag beheben

Wenn ein Anpassungsschritt fehlschlägt, beendet Image Builder standardmäßig die Ausführung und löscht die Worker-VM sofort, um Kosten zu senken.

Wenn Sie Skripts interaktiv debuggen möchten, können Sie das Flag debug aktivieren. Dadurch bleibt die VM aktiv und Sie können über SSH eine direkte Verbindung zum aktiven Gastsystem herstellen.

Debug-Flag aktivieren

Legen Sie in der Datei imagebuilder.yaml debug: true im Block infrastructureConfig fest:

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

Build auslösen und auf Fehler warten

Reichen Sie Ihren Build mit Standardmethoden ein. Wenn in der Pipeline ein Skriptfehler auftritt, passiert Folgendes:

  1. Der Orchestrator pausiert die Ausführung des Builds.
  2. Image Builder löscht die Worker-VM nicht. Sie wird weiterhin in Ihrem Projekt ausgeführt.
  3. Die VM bleibt für die in der Eigenschaft instanceDurationHours angegebene Zeit aktiv, bevor sie automatisch beendet wird.

Verbindung zur Worker-VM herstellen, um Fehler zu beheben

Sehen Sie sich die Cloud Build-Konsolenausgabe an, um den Namen der aktiven Worker-VM-Instanz abzurufen. Öffnen Sie ein Terminal und stellen Sie mit gcloud compute ssh eine Verbindung zur Worker-VM her:

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

Wenn in Ihrer imagebuilder.yaml-Datei externalIP: none konfiguriert ist, was zu keiner externen IP-Adresse führt, fügen Sie das Flag --tunnel-through-iap ein, um eine Verbindung über die TCP-Weiterleitung von Identity-Aware Proxy (IAP) herzustellen:

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

Sobald die Verbindung hergestellt ist, können Sie Befehle in Echtzeit ausführen, Zieldateien prüfen, laufende Prozesse analysieren, Protokolle des Installationsverlaufs aufrufen und Skriptänderungen direkt auf der Festplatte testen.

Zwischen-Debug-Bilder analysieren

Alternativ dazu, die Worker-VM mit dem Flag debug aktiv zu halten, können Sie den Laufwerkstatus mit dem automatisch generierten Debug-Image analysieren:

  1. Wenn ein Build mit debug: false (Standard) fehlschlägt, exportiert der Orchestrator das teilweise angepasste Bootlaufwerk als Compute Engine-Image.
  2. Das Debug-Image wird mit dem Muster image-builder-debug-image-BUILD_ID benannt und der Image-Familie image-builder-debug-images zugewiesen.

  3. Wenn Sie das Dateisystem untersuchen möchten, erstellen Sie eine temporäre VM-Instanz mit diesem Debug-Image als Bootlaufwerk:

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

  4. Stellen Sie eine Verbindung zur temp-debug-vm-Instanz her, um das Laufwerk zu prüfen und die Ursache für den Fehler bei der Anpassung zu ermitteln.

Cloud Build-Timeouts beheben

Wenn die Ausführung einer Image Builder-Pipeline länger als erwartet dauert, wird der Cloud Build-Job beendet und schlägt mit dem Status TIMEOUT fehl.

Die Build-Zeiten können variieren und sind in der Regel bei größeren Maschinentypen länger. Legen Sie das Zeitlimit so fest, dass genügend Zeit für den Build zur Verfügung steht. Wenn nicht festgelegt, beträgt das standardmäßige Cloud Build-Zeitlimit 1 Stunde (3600s).

Wenn Sie ein längeres Zeitlimit konfigurieren möchten, legen Sie das Feld timeout auf der Stammebene der Datei cloudbuild.yaml fest:

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'

Nachdem Sie den Zeitüberschreitungswert aktualisiert haben, führen Sie den Build noch einmal aus und prüfen Sie, ob die Image Builder-Pipeline vollständig ausgeführt werden kann.

Weitere Informationen zum Parameter timeout finden Sie in der Cloud Build-Dokumentation unter timeout.