Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Finden Sie die Ursache für eine fehlgeschlagene Image-Erstellung im Fehlerkontext
Wenn ein Image-Build fehlschlägt, meldet Image Builder den Fehler im Image`state`. Der Status enthält eine Meldung, die den Fehler beschreibt`reason`, sowie einen strukturierten **Fehlerkontext**`failureContext`.
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 [GetImage[ListImagePipelineImages](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImagePipelineImages.html)](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetImage.html)API-Operationen, und zurück und zeigt ihn im Image Builder an AWS-Managementkonsole. [ListImageBuildVersions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImageBuildVersions.html)
**Topics**
+ [Was beinhaltet der Fehlerkontext](#image-failure-context-fields)
+ [Den Fehlerkontext für ein fehlerhaftes Image anzeigen](#image-failure-context-view)
+ [Verfolgen Sie einen Fehler bis zu seiner Ursache](#image-failure-context-rca)
+ [Verwenden Sie den Fehlerkontext mit KI-Agenten](#image-failure-context-ai)
+ [Überlegungen](#image-failure-context-considerations)
## 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 [ImageState](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageState.html)in 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 [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)sich um dieselben Werte wie bei [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)und, 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 unter[Aktionsmodule unterstützt von AWSTOE Komponentenmanager](toe-action-modules.md).
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](#image-failure-context-view) 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/](https://console.aws.amazon.com/imagebuilder/).
1. 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.
1. 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 Sie`imageStatus`, 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.
1. **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.
1. **Untersuchen Sie die Details zur Workflow-Laufzeit.** Rufen Sie [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)mit `workflowExecutionId` an, um jeden Schritt im Workflow und die Position des fehlgeschlagenen Schritts in der Reihenfolge zu sehen. Rufen Sie [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)mit 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}}
```
1. **Lesen Sie die Protokolle für den fehlgeschlagenen Schritt.** Verwenden Sie `workflowExecutionId` und`failedStep`, 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](#image-failure-context-logs).
1. **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](troubleshooting.md#troubleshooting-pipelines).
### 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}}
```
`ComponentArn`ist derselbe Wert, der `componentFailure.componentArn` gemeldet wird. Verwenden Sie ihn also, um den Protokollblock dem Fehlerkontext für ein Bild zuzuordnen. `Document`ist der Wert`name`, 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](monitor-cwlogs.md). Informationen zu den Dateien, die AWSTOE dabei entstehen, und zu den Inhalten der einzelnen Dateien finden Sie unter[Protokollierung von Komponenten](toe-use-documents.md#component-logging).
## 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](devops-agent-troubleshooting.md).
+ **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 unter[Beheben Sie Fehler bei Builds mit einem AI-Codierungsagenten](agent-toolkit-skill.md).
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 auch`failureContext`. 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.