Finden Sie die Ursache für eine fehlgeschlagene Image-Erstellung im Fehlerkontext

Wenn ein Image-Build fehlschlägt, meldet Image Builder den Fehler im Imagestate. Der Status enthält eine Meldung, die den Fehler beschreibtreason, sowie einen strukturierten FehlerkontextfailureContext.

Der Fehlerkontext besteht aus einer Reihe von Feldern, in denen der Workflow, der Workflow-Schritt, der Komponentenschritt und die am Fehler beteiligten Zielregionen benannt werden. Da die Felder strukturiert sind, kann Ihre Automatisierung direkt auf sie zugreifen, und Sie können ihre Werte an andere Image Builder Builder-API-Operationen übergeben, um mehr Details zu erhalten.

Image Builder gibt den Fehlerkontext aus den GetImageListImagePipelineImagesAPI-Operationen, und zurück und zeigt ihn im Image Builder an AWS-Managementkonsole. ListImageBuildVersions

Was beinhaltet der Fehlerkontext

Der Fehlerkontext beschreibt einen Fehler auf drei Ebenen. Jedes Mitglied ist optional, und Image Builder gibt nur die Mitglieder zurück, die für den Fehler gelten. Informationen zu den Mitgliedern, ihren Typen und ihren Einschränkungen finden Sie ImageStatein der EC2 Image Builder API-Referenz.

Das Bild

In welcher Phase sich das Image befand, als es fehlschlug, und welcher Workflow und welcher Workflow-Schritt ausgeführt wurden. Bei den Kennungen für den Workflow und die Schrittausführung handelt es GetWorkflowStepExecutionsich um dieselben Werte wie bei ListWorkflowStepExecutionsund, sodass Sie sie direkt an diese Operationen übergeben können.

Der Schritt der Komponente

Bei einem Build- oder Testfehler, den eine Komponente verursacht hat, die Komponente, die ausgeführt wurde, die Phase und der Schritt innerhalb des Dokuments, das AWSTOE Aktionsmodul, das der Schritt ausgeführt hat, und der Fehler, den der Schritt gemeldet hat. Image Builder identifiziert die Komponente anhand der Build-Version und benennt daher genau die Revision, die ausgeführt wurde, auch wenn Ihr Rezept auf eine Wildcard-Version verweist. Informationen zu den Aktionsmodulen finden Sie unterAktionsmodule unterstützt von AWSTOE Komponentenmanager.

Die Zielregionen

Bei einem Verteilungs- oder Integrationsfehler ein Zusammenfassungsfehler für die gesamte Verteilung und ein Eintrag für jedes Ziel, das fehlgeschlagen ist. Jeder Eintrag enthält die Art und Weise, wie die Verteilung dort endete, den Fehler des Dienstes, den Image Builder aufgerufen hat, und, bei einer kontoübergreifenden Verteilung, das Ziel, an AWS-Konto das Image Builder verteilt hat. Wenn die AMI-Kopie erfolgreich war, ein darauf folgender Schritt jedoch nicht, benennt der Eintrag auch diesen Schritt — das Zuordnen von Lizenzkonfigurationen, das Aktualisieren von Startvorlagen, das Einfügen von SSM-Parametern, das Aktualisieren von Amazon EC2 Fast Launch-Konfigurationen oder das Exportieren des AMI. Erfolgreiche Ziele werden weggelassen.

Anmerkung

Welche Mitglieder Image Builder zurückgibt, hängt davon ab, wie weit der Build fortgeschritten ist. Ein Fehler, der auftritt, bevor Image Builder einen Workflow startet, hat keinen zu benennenden Workflow. Wenn das übergeordnete Bild in Ihrem Rezept beispielsweise nicht mehr existiert, identifiziert der Fehlerkontext die Phase und nichts weiter.

Die Beispiele unter Den Fehlerkontext für ein fehlerhaftes Image anzeigen zeigen die Elemente, die Image Builder für einen Komponentenfehler und für einen Verteilungsfehler zurückgibt.

Den Fehlerkontext für ein fehlerhaftes Image anzeigen

Fehlerkontext in der Image Builder Builder-Konsole anzeigen

Image Builder zeigt die Fehlerdetails für ein Image überall dort an, wo ein Failed Image-Status angezeigt wird.

1. Öffnen Sie die EC2 Image Builder Builder-Konsole unter https://console.aws.amazon.com/imagebuilder/.

2. Wählen Sie im Navigationsbereich Images und dann die fehlgeschlagene Image-Build-Version aus. Sie können auch die Liste der Ausgabebilder für eine Pipeline öffnen.

3. Wählen Sie den Status des Failed Bilds aus. Image Builder zeigt die Fehlerdetails für das Image an und verknüpft den fehlgeschlagenen Workflow-Schritt mit den zugehörigen Laufzeitdetails.

Ruft den Fehlerkontext mit dem ab AWS CLI

Führen Sie den get-image Befehl mit der Build-Version ARN des fehlgeschlagenen Images aus.

aws imagebuilder get-image \
    --image-build-version-arn arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1 \
    --query "image.state"

Die folgende Beispielausgabe zeigt einen Build, der fehlgeschlagen ist, weil in einem Komponentenschritt ein Skript ausgeführt wurde, das mit einem Status ungleich Null beendet wurde.

{
    "status": "FAILED",
    "reason": "Workflow Execution ID: 'wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' failed with reason: Document arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1 failed!",
    "failureContext": {
        "imageStatus": "BUILDING",
        "workflowExecutionId": "wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "workflowArn": "arn:aws:imagebuilder:us-west-2:aws:workflow/build/build-image/x.x.x/x",
        "stepExecutionId": "step-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
        "failedStep": "ApplyBuildComponents",
        "componentFailure": {
            "componentArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1",
            "phaseName": "build",
            "stepName": "InstallPackages",
            "action": "ExecuteBash",
            "errorMessage": "exit status 1"
        }
    }
}

Die nächste Beispielausgabe zeigt ein Image, das erfolgreich erstellt und getestet wurde und dann fehlschlug, während Image Builder die Startvorlagen in drei Zielregionen aktualisierte. Der Build war in allen anderen Destinationen erfolgreich, sodass nur die drei fehlerhaften Regionen angezeigt werden.

{
    "status": "FAILED",
    "reason": "Integration failed with JobId 'a1b2c3d4-5678-90ab-cdef-EXAMPLE33333', status = 'Failed' for ARN 'arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1'. …",
    "failureContext": {
        "imageStatus": "INTEGRATING",
        "distributionFailure": {
            "errorMessage": "In region 'eu-west-1' - 'EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'' …",
            "regionFailures": [
                {
                    "region": "eu-west-1",
                    "status": "FAILED",
                    "imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
                    "errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'"
                },
                {
                    "region": "us-east-1",
                    "status": "FAILED",
                    "imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
                    "errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-1a2b3c4d5EXAMPLE' does not exist'"
                },
                {
                    "region": "us-east-2",
                    "status": "FAILED",
                    "imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
                    "errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-2a3b4c5d6EXAMPLE' does not exist'"
                }
            ]
        }
    }
}

Um die fehlgeschlagenen Builds in einem Konto zu finden, ohne jede einzelne zu überprüfen, listen Sie die Image-Build-Versionen auf und filtern Sie nach dem Image-Status. Im folgenden Beispiel werden die fehlgeschlagenen Builds für ein Image mit dem jeweiligen Fehlerkontext zurückgegeben.

aws imagebuilder list-image-build-versions \
    --image-version-arn arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0 \
    --query "imageSummaryList[?state.status=='FAILED'].[arn, state.failureContext]"

Verfolgen Sie einen Fehler bis zu seiner Ursache

Durch den Kontext eines Fehlers wird ein Fehler auf einen einzigen Schritt eingegrenzt. Gehen Sie wie folgt vor, um von diesem Schritt zu den Beweisen zu gelangen, die ihn erklären.

1. Lesen SieimageStatus, um die Phase zu finden, die fehlgeschlagen ist. Ein Wert von BUILDING oder TESTING bedeutet, dass der Fehler auf der Amazon EC2 EC2-Instance aufgetreten ist, die Image Builder gestartet hat. Daher sind die Komponentenprotokolle der nächste Ort, an dem gesucht werden muss. Der Wert DISTRIBUTING oder INTEGRATING bedeutet, dass das Image erstellt wurde und der Fehler in Ihren Distributionseinstellungen oder in einem Zielkonto oder liegt.

2. Lesen Sie das Mitglied, das den spezifischen Fehler beschreibt. Falls componentFailure vorhanden, identifiziert es den fehlgeschlagenen Schritt in Ihrem Komponentendokument sowie die Aktion, die der Schritt ausgeführt hat, und den Fehler, den er gemeldet hat. Wenn distributionFailure vorhanden, regionFailures gibt Ihnen jeder Eintrag in ein Ziel und einen eigenen Fehler.

3. Untersuchen Sie die Details zur Workflow-Laufzeit. Rufen Sie ListWorkflowStepExecutionsmit workflowExecutionId an, um jeden Schritt im Workflow und die Position des fehlgeschlagenen Schritts in der Reihenfolge zu sehen. Rufen Sie GetWorkflowStepExecutionmit auf, stepExecutionId um die Eingaben, Ausgaben und den Rollback-Status des fehlgeschlagenen Schritts selbst zu erfahren.

   Das folgende Beispiel listet die Schritte für eine fehlgeschlagene Workflow-Ausführung auf.

   aws imagebuilder list-workflow-step-executions \
       --workflow-execution-id wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

4. Lesen Sie die Protokolle für den fehlgeschlagenen Schritt. Verwenden Sie workflowExecutionId undfailedStep, um direkt zum Protokollpfad für diesen Schritt zu gelangen. Weitere Informationen finden Sie unter Rufen Sie die vollständige Komponentenausgabe aus den Protokollen ab.

5. Reproduzieren Sie den Fehler, falls erforderlich. Um die Build-Instance am Laufen zu halten, sodass Sie eine Verbindung zu ihr herstellen können, deaktivieren Sie die Einstellung Instanz bei Fehler beenden in der Infrastrukturkonfiguration, die Ihre Pipeline verwendet. Weitere Informationen finden Sie unter Fehler bei Pipeline-Builds.

Rufen Sie die vollständige Komponentenausgabe aus den Protokollen ab

Der Fehlerkontext meldet den Fehler, den ein Komponentenschritt ausgelöst hat, aber nicht die Standardausgabe und den Standardfehler des Skripts, das der Schritt ausgeführt hat. Image Builder speichert diese Ausgabe in den Komponentenprotokollen.

Wenn eine Komponente ausfällt, werden die Details des ersten fehlgeschlagenen Schritts in das Konsolenprotokoll AWSTOE geschrieben, gefolgt von der vollständigen Standardfehlerausgabe für diesen Schritt.

  Document: MyExampleDocument
  ComponentArn: arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1
  Phase: build
  Step: InstallPackages
  Action: ExecuteBash
  ErrorMessage: exit status 1
  Stderr: the full standard error output of the step

ComponentArnist derselbe Wert, der componentFailure.componentArn gemeldet wird. Verwenden Sie ihn also, um den Protokollblock dem Fehlerkontext für ein Bild zuzuordnen. Documentist der Wertname, den das Komponentendokument deklariert und den der Autor unabhängig von der Komponentenressource auswählt, sodass sich die beiden unterscheiden können und Document allein nicht identifiziert werden kann, welche Komponente ausgefallen ist.

AWSTOE schreibt ErrorMessage und Stderr nur, wenn der fehlgeschlagene Schritt sie erzeugt hat.

Image Builder streamt die Komponentenprotokolle an Amazon CloudWatch Logs, wenn der Build abgeschlossen ist. Wenn Sie in Ihrer Infrastrukturkonfiguration einen Amazon S3 S3-Bucket angegeben haben, schreibt Image Builder ihn auch dort. Die Namen der Protokollgruppen und Streams finden Sie unterÜberwachen Sie Image Builder Builder-Protokolle mit Amazon CloudWatch Logs. Informationen zu den Dateien, die AWSTOE dabei entstehen, und zu den Inhalten der einzelnen Dateien finden Sie unterProtokollierung von Komponenten.

Verwenden Sie den Fehlerkontext mit KI-Agenten

Der Fehlerkontext ist so konzipiert, dass er sowohl von der Automatisierung als auch von Menschen gelesen werden kann. Ein KI-Agent, der Fehler bei einem fehlgeschlagenen Build behebt, liest die benannten Felder und verwendet ihre Werte als Argumente für den nächsten API-Aufruf. Dadurch ist eine Diagnose wiederholbar und der Agent muss nicht erraten, welche Komponente er untersuchen soll.

Sie können den Fehlerkontext auf eine der folgenden Arten verwenden:

• Problembehandlung im Image Builder AWS-Managementkonsole — Die vom AWS DevOps Agenten bereitgestellte Problembehandlungsfunktion verwendet den Fehlerkontext, um ihre Untersuchung auf den Workflow-Schritt und die Komponente zu beschränken, die ausgefallen sind, bevor sie Protokolle und zugehörige Ressourcen untersucht. Weitere Informationen finden Sie unter Beheben Sie fehlgeschlagene Builds mit KI — Vorschau.

• Ihr eigener KI-Codierungsagent — Ein Agent, der anruft, GetImage erhält in der Antwort den Fehlerkontext und kann ihm auf die gleiche Weise folgen. Informationen dazu, wie Sie Ihrem Agenten die umfassenderen Image Builder Builder-Kenntnisse vermitteln können, die er benötigt, um auf die Ergebnisse reagieren zu können, finden Sie unterBeheben Sie Fehler bei Builds mit einem AI-Codierungsagenten.

Wenn Sie Ihre eigene Automatisierung im Fehlerkontext erstellen, behandeln Sie jedes Element als optional und überprüfen Sie, ob es sich um Elemente handelt, die Sie verwenden, und nicht, ob es failureContext selbst vorhanden ist. Welche Mitglieder Image Builder zurückgibt, hängt vom Fehler ab, und Image Builder kann im Laufe der Zeit Mitglieder hinzufügen.

Überlegungen

Beachten Sie Folgendes, wenn Sie den Fehlerkontext verwenden:

• Image Builder gibt den Fehlerkontext nur für fehlgeschlagene Bilder zurück. Ein erfolgreiches Image und ein Image, das Sie storniert haben, haben es nicht.

• Ein fehlgeschlagenes Bild enthält reason sowohl als auchfailureContext. Verwenden Sie diese Option, reason um eine lesbare Zusammenfassung des Fehlers zu erhalten und ihn failureContext zu lokalisieren.

• Wenn eine Komponente die ExecuteDocument Aktion verwendet, um ein verschachteltes Dokument auszuführen, identifiziert der Fehlerkontext die Komponente, die Image Builder anhand Ihres Rezepts ausgeführt hat, nicht das verschachtelte Dokument.

• Fehlermeldungen im Fehlerkontext sind in ihrer Länge begrenzt und können gekürzt werden. Die Komponentenprotokolle enthalten die gesamte Ausgabe.

• Der Fehlerkontext meldet den ersten fehlgeschlagenen Schritt. Wenn mehr als ein Schritt fehlgeschlagen ist, überprüfen Sie die Workflow-Schrittausführungen und die Komponentenprotokolle für den Rest.

• Fehlermeldungen können Text enthalten, den eine Komponente oder ein anderer AWS Dienst erzeugt hat. Behandeln Sie sie als nicht vertrauenswürdige Eingabe, wenn Sie sie rendern oder an ein anderes System weitergeben.