Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Trouvez la cause de l'échec de la création d'une image avec un contexte d'échec
En cas d'échec de la création d'une image, Image Builder signale l'échec dans l'image`state`. L'état contient un message décrivant la défaillance dans `reason` et un **contexte de défaillance** structuré dans`failureContext`.
Le contexte de défaillance est un ensemble de champs qui nomment le flux de travail, l'étape du flux de travail, l'étape du composant et les régions de destination impliquées dans l'échec. Les champs étant structurés, votre automatisation peut s'y rattacher directement, et vous pouvez transmettre leurs valeurs à d'autres opérations de l'API Image Builder pour obtenir plus de détails.
Image Builder renvoie le contexte d'échec des opérations [GetImage[ListImageBuildVersions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImageBuildVersions.html)](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetImage.html), et [ListImagePipelineImages](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImagePipelineImages.html)API, et l'affiche dans Image Builder Console de gestion AWS.
**Topics**
+ [Ce que contient le contexte de défaillance](#image-failure-context-fields)
+ [Afficher le contexte de défaillance d'une image défaillante](#image-failure-context-view)
+ [Retracez une défaillance jusqu'à sa cause première](#image-failure-context-rca)
+ [Utiliser le contexte de défaillance avec les agents d'IA](#image-failure-context-ai)
+ [Considérations](#image-failure-context-considerations)
## Ce que contient le contexte de défaillance
Le contexte de défaillance décrit une défaillance à trois niveaux. Chaque membre est facultatif, et Image Builder renvoie uniquement les membres concernés par l'échec. Pour les membres, leurs types et leurs contraintes, consultez le manuel de référence [ImageState](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageState.html)de l'*API EC2 Image Builder*.
L'image
À quel stade se trouvait l'image lorsqu'elle a échoué, et quel flux de travail et quelle étape du flux de travail étaient en cours d'exécution. Les identificateurs du flux de travail et d'exécution des étapes sont les mêmes valeurs que [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)et [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)prennent, vous pouvez donc les transmettre directement à ces opérations.
L'étape du composant
En cas d'échec de génération ou de test provoqué par un composant, le composant qui s'est exécuté, la phase et l'étape de son document, le module AWSTOE d'action exécuté par l'étape et l'erreur signalée par l'étape. Image Builder identifie le composant par version de build. Il nomme donc la révision exacte exécutée même lorsque votre recette fait référence à une version générique. Pour les modules d'action, voir[Modules d'action pris en charge par AWSTOE gestionnaire de composants](toe-action-modules.md).
Les régions de destination
En cas d'échec de distribution ou d'intégration, une erreur récapitulative pour la distribution dans son ensemble et une entrée pour chaque destination défaillante. Chaque entrée indique la façon dont la distribution s'est arrêtée là, l'erreur du service appelé par Image Builder et, dans le cas d'une distribution entre comptes, la cible à Compte AWS laquelle Image Builder a distribué. Lorsque la copie de l'AMI a réussi mais pas l'étape suivante, l'entrée nomme également cette étape : association des configurations de licence, mise à jour des modèles de lancement, mise à jour des paramètres SSM, mise à jour des configurations de lancement rapide d'Amazon EC2 ou exportation de l'AMI. Les destinations réussies sont omises.
**Note**
Les membres renvoyés par Image Builder dépendent de l'état d'avancement de la construction. Un échec qui survient avant qu'Image Builder ne démarre un flux de travail n'a aucun flux de travail à nommer. Par exemple, si l'image parent de votre recette n'existe plus, le contexte d'échec identifie l'étape et rien de plus.
Les exemples ci-dessous [Afficher le contexte de défaillance d'une image défaillante](#image-failure-context-view) montrent les membres renvoyés par Image Builder en cas de défaillance d'un composant ou d'un échec de distribution.
## Afficher le contexte de défaillance d'une image défaillante
**Afficher le contexte de défaillance dans la console Image Builder**
Image Builder affiche les détails de la défaillance d'une image chaque fois qu'il affiche `Failed` l'état de l'image.
1. Ouvrez la console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)EC2 Image Builder à l'adresse.
1. Choisissez **Images** dans le volet de navigation, puis choisissez la version de création de l'image qui a échoué. Vous pouvez également ouvrir la liste **des images de sortie** d'un pipeline.
1. Choisissez le statut de `Failed` l'image. Image Builder affiche les détails de l'échec de l'image et lie l'étape du flux de travail qui a échoué aux détails de son exécution.
**Obtenez le contexte des défaillances à l'aide du AWS CLI**
Exécutez la **get-image** commande avec l'ARN de la version de compilation de l'image défaillante.
```
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"
```
L'exemple de sortie suivant montre une compilation qui a échoué parce qu'une étape du composant a exécuté un script qui s'est terminé avec un statut différent de zéro.
```
{
"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"
}
}
}
```
L'exemple de sortie suivant montre une image qui a été créée et testée avec succès, puis qui a échoué pendant qu'Image Builder mettait à jour les modèles de lancement dans trois régions de destination. La compilation a réussi dans toutes les autres destinations, de sorte que seules les trois régions ayant échoué apparaissent.
```
{
"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'"
}
]
}
}
}
```
Pour rechercher les versions ayant échoué dans un compte sans inspecter chacune d'elles, listez les versions de génération d'image et filtrez en fonction de l'état de l'image. L'exemple suivant renvoie les compilations ayant échoué pour une image, avec le contexte d'échec pour chacune d'entre elles.
```
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]"
```
## Retracez une défaillance jusqu'à sa cause première
Le contexte de défaillance réduit l'échec à une seule étape. Suivez les étapes suivantes pour passer de cette étape aux preuves qui l'expliquent.
1. **Lisez `imageStatus` pour trouver l'étape qui a échoué.** Une valeur de `BUILDING` ou `TESTING` signifie que la défaillance s'est produite sur l'instance Amazon EC2 lancée par Image Builder. Les journaux des composants sont donc le prochain endroit à consulter. Une valeur de `DISTRIBUTING` ou `INTEGRATING` signifie que l'image a été créée et que l'échec se situe dans vos paramètres de distribution ou dans un compte de destination ou.
1. **Lisez le membre qui décrit l'échec spécifique.** S'il `componentFailure` est présent, il identifie l'étape défaillante dans le document de votre composant, ainsi que l'action exécutée par l'étape et l'erreur signalée. S'`distributionFailure`il est présent, chaque entrée vous `regionFailures` donne une destination et sa propre erreur.
1. **Inspectez les détails de l'exécution du flux de travail.** Appelez [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)`workflowExecutionId`pour voir chaque étape du flux de travail et où se situe l'étape qui a échoué dans la séquence. Appelez [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)with `stepExecutionId` pour connaître les entrées, les sorties et l'état d'annulation de l'étape échouée elle-même.
L'exemple suivant répertorie les étapes d'échec de l'exécution d'un flux de travail.
```
aws imagebuilder list-workflow-step-executions \
--workflow-execution-id wf-{{a1b2c3d4-5678-90ab-cdef-EXAMPLE11111}}
```
1. **Lisez les journaux de l'étape qui a échoué.** Utilisez `workflowExecutionId` et `failedStep` pour accéder directement au chemin du journal pour cette étape. Pour plus d’informations, consultez [Obtenez la sortie complète du composant à partir des journaux](#image-failure-context-logs).
1. **Reproduisez l'échec si nécessaire.** Pour que l'instance de build continue de fonctionner afin que vous puissiez vous y connecter, désactivez le paramètre **Terminate instance en cas d'échec** dans la configuration de l'infrastructure utilisée par votre pipeline. Pour plus d’informations, consultez [Résoudre les problèmes liés aux builds de pipelines](troubleshooting.md#troubleshooting-pipelines).
### Obtenez la sortie complète du composant à partir des journaux
Le contexte de défaillance indique l'erreur générée par une étape du composant, mais pas le résultat standard ni l'erreur standard du script exécuté par l'étape. Image Builder conserve cette sortie dans les journaux des composants.
Lorsqu'un composant échoue, AWSTOE écrit les détails de la première étape échouée dans le journal de la console, puis le résultat d'erreur standard complet pour cette étape.
```
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`est la même valeur que celle `componentFailure.componentArn` signalée. Utilisez-la donc pour faire correspondre le bloc de journal au contexte de défaillance d'une image. `Document`est `name` celui que le document du composant déclare, que l'auteur choisit indépendamment de la ressource du composant, de sorte que les deux peuvent différer et ne permettent pas à `Document` eux seuls d'identifier le composant défaillant.
AWSTOE écrit `ErrorMessage` et `Stderr` uniquement lorsque l'étape échouée les a produites.
Image Builder diffuse les journaux des composants vers Amazon CloudWatch Logs une fois la génération terminée. Si vous avez spécifié un compartiment Amazon S3 dans la configuration de votre infrastructure, Image Builder l'y écrit également. Pour les noms des groupes de journaux et des flux, consultez[Surveillez les journaux d'Image Builder avec Amazon CloudWatch Logs](monitor-cwlogs.md). Pour connaître les fichiers AWSTOE produits et le contenu de chacun d'entre eux, reportez-vous à[Journalisation des composants](toe-use-documents.md#component-logging).
## Utiliser le contexte de défaillance avec les agents d'IA
Le contexte de défaillance est conçu pour être lu par l'automatisation ainsi que par les personnes. Un agent d'intelligence artificielle qui résout les problèmes liés à un échec de compilation lit les champs nommés et utilise leurs valeurs comme arguments pour le prochain appel d'API qu'il effectue. Cela rend le diagnostic répétable et empêche l'agent de deviner quel composant ou de quel composant il doit étudier.
Vous pouvez utiliser le contexte de défaillance de l'une des manières suivantes :
+ **Résolution des problèmes dans Image Builder Console de gestion AWS** : la fonctionnalité de résolution des problèmes, développée par l' AWS DevOps agent, utilise le contexte de défaillance pour étendre son enquête à l'étape du flux de travail et au composant défaillant avant d'examiner les journaux et les ressources associées. Pour plus d’informations, consultez [Résoudre les problèmes liés aux builds échoués grâce à l'IA - Aperçu](devops-agent-troubleshooting.md).
+ **Votre propre agent de codage AI** : un agent qui appelle `GetImage` reçoit le contexte d'échec dans la réponse et peut le suivre de la même manière. Pour donner à votre agent les connaissances approfondies dont il a besoin sur Image Builder pour agir en fonction de ce qu'il trouve, consultez[Résoudre les problèmes liés aux builds à l'aide d'un agent de codage AI](agent-toolkit-skill.md).
Si vous créez votre propre automatisation en fonction du contexte de défaillance, considérez chaque membre comme facultatif et vérifiez les membres que vous utilisez plutôt que leur `failureContext` présence. Les membres renvoyés par Image Builder dépendent de l'échec, et Image Builder peut ajouter des membres au fil du temps.
## Considérations
Notez ce qui suit lorsque vous utilisez le contexte de défaillance :
+ Image Builder renvoie le contexte d'échec uniquement pour les images défaillantes. Une image réussie et une image que vous avez annulée ne l'ont pas.
+ Une image défectueuse contient à la fois `reason` et`failureContext`. `reason`À utiliser pour un résumé lisible de la panne et `failureContext` pour la localiser.
+ Si un composant utilise cette `ExecuteDocument` action pour exécuter un document imbriqué, le contexte d'échec identifie le composant qu'Image Builder a exécuté à partir de votre recette, et non le document imbriqué.
+ Les messages d'erreur en cas de défaillance sont limités en longueur et peuvent être tronqués. Les journaux des composants contiennent la sortie complète.
+ Le contexte d'échec indique la première étape qui a échoué. Si plusieurs étapes ont échoué, passez en revue les exécutions des étapes du flux de travail et les journaux des composants pour le reste.
+ Les messages d'erreur peuvent contenir du texte produit par un composant ou un autre AWS service. Traitez-les comme des entrées non fiables si vous les restituez ou les transmettez à un autre système.