本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 尋找具有失敗內容的失敗映像建置原因
當映像建置失敗時，映像建置器會在映像 中報告失敗`state`。狀態附帶一則訊息，說明 中的失敗`reason`，以及 中的結構化**失敗內容**`failureContext`。
失敗內容是一組欄位，命名工作流程、工作流程步驟、元件步驟，以及涉及失敗的目的地區域。由於欄位是結構化的，因此您的自動化可以直接對其進行分支，而且您可以將其值傳遞給其他 Image Builder API 操作，以取得更多詳細資訊。
Image Builder 會從 [GetImage](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetImage.html)、[ListImageBuildVersions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImageBuildVersions.html) 和 [ListImagePipelineImages](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImagePipelineImages.html) API 操作傳回失敗內容，並將其顯示在 Image Builder 中 AWS 管理主控台。
**Topics**
+ [失敗內容包含哪些內容](#image-failure-context-fields)
+ [檢視失敗映像的失敗內容](#image-failure-context-view)
+ [追蹤故障至其根本原因](#image-failure-context-rca)
+ [搭配 AI 代理器使用失敗內容](#image-failure-context-ai)
+ [考量事項](#image-failure-context-considerations)
## 失敗內容包含哪些內容
失敗內容說明三個層級的失敗。每個成員都是選用的，而映像建置器只會傳回適用於失敗的成員。如需成員、其類型及其限制，請參閱 *EC2 Image Builder API 參考中的 ImageState*[ImageState](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageState.html)。
映像
映像失敗時處於哪個階段，以及正在執行哪個工作流程和工作流程步驟。工作流程和步驟執行識別符與 [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html) 和 [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html) 採用的值相同，因此您可以將它們直接傳遞至這些操作。
元件步驟
對於元件導致的建置或測試失敗、執行的元件、其文件中的階段和步驟、步驟執行 AWS TOE 的動作模組，以及步驟回報的錯誤。Image Builder 會依組建版本識別元件，因此它會命名確切的修訂，即使您的配方參考萬用字元版本。如需 動作模組，請參閱 [AWS TOE 元件管理員支援的動作模組](toe-action-modules.md)。
目的地區域
對於分佈或整合失敗，分佈整體的摘要錯誤，以及每個失敗目的地的一個項目。每個項目都攜帶其 、分佈的結束方式、Image Builder 呼叫之服務的錯誤，以及跨帳戶分佈的 Image Builder AWS 帳戶 分佈目標。當 AMI 複製成功但未成功執行步驟時，項目也會命名該步驟：關聯授權組態、更新啟動範本、放置 SSM 參數、更新 Amazon EC2 Fast Launch 組態，或匯出 AMI。會省略成功的目標。
**注意**
Image Builder 傳回哪些成員取決於建置進度。在 Image Builder 啟動工作流程之前發生的失敗沒有要命名的工作流程。例如，如果您配方中的父系映像不再存在，失敗內容會識別階段，不會再識別任何內容。
中的範例[檢視失敗映像的失敗內容](#image-failure-context-view)顯示 Image Builder 針對元件故障和分佈故障傳回的成員。
## 檢視失敗映像的失敗內容
**在映像建置器主控台中檢視失敗內容**
Image Builder 會在影像顯示影像狀態的任何地方顯示`Failed`影像的失敗詳細資訊。
1. 開啟 EC2 Image Builder 主控台，位於 [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 從導覽窗格中選擇**影像**，然後選擇失敗的影像建置版本。您也可以開啟管道的**輸出映像**清單。
1. 選擇`Failed`影像狀態。映像建置器會顯示映像的失敗詳細資訊，並將失敗的工作流程步驟連結至其執行時間詳細資訊。
**使用 取得失敗內容 AWS CLI**
使用失敗映像的建置版本 ARN 執行 **get-image**命令。
```
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"
```
下列範例輸出顯示因元件步驟執行以非零狀態結束的指令碼而失敗的建置。
```
{
"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"
}
}
}
```
下一個範例輸出顯示成功建置和測試的映像，然後在映像建置器更新三個目的地區域中的啟動範本時失敗。建置在所有其他目的地都成功，因此只會顯示三個失敗的區域。
```
{
"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'"
}
]
}
}
}
```
若要在帳戶中尋找失敗的組建而不檢查每個組建，請列出映像組建版本並篩選映像狀態。下列範例會傳回映像的失敗組建，以及每個映像的失敗內容。
```
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]"
```
## 追蹤故障至其根本原因
失敗內容會將失敗縮小為單一步驟。使用下列步驟從該步驟移至說明該步驟的證據。
1. **閱讀`imageStatus`以尋找失敗的階段。**值為 `BUILDING`或 `TESTING`表示 Image Builder 啟動的 Amazon EC2 執行個體發生故障，因此元件日誌是下一個要查看的位置。值為 `DISTRIBUTING`或 `INTEGRATING`表示映像已建置，且失敗位於您的分佈設定或目的地帳戶或 中。
1. **閱讀描述特定失敗的成員。**如果 `componentFailure` 存在，它會識別元件文件中的失敗步驟，以及步驟執行的動作及其回報的錯誤。如果 `distributionFailure` 存在， 中的每個項目`regionFailures`都會為您提供目的地及其本身的錯誤。
1. **檢查工作流程執行時間詳細資訊。**使用 呼叫 [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)`workflowExecutionId`，以查看工作流程中的每個步驟，以及失敗步驟的順序。使用 呼叫 [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)，`stepExecutionId`以取得失敗步驟本身的輸入、輸出和轉返狀態。
下列範例列出失敗工作流程執行的步驟。
```
aws imagebuilder list-workflow-step-executions \
--workflow-execution-id wf-{{a1b2c3d4-5678-90ab-cdef-EXAMPLE11111}}
```
1. **讀取失敗步驟的日誌。**使用 `workflowExecutionId`和 `failedStep` 直接前往該步驟的日誌路徑。如需詳細資訊，請參閱[從日誌取得完整的元件輸出](#image-failure-context-logs)。
1. **如果需要，請重新產生失敗。**若要讓建置執行個體保持執行狀態，以便可以連線到它，請在管道使用的基礎設施組態中清除**故障時終止執行個體**設定。如需詳細資訊，請參閱[管道建置疑難排解](troubleshooting.md#troubleshooting-pipelines)。
### 從日誌取得完整的元件輸出
失敗內容會報告元件步驟引發的錯誤，但不會報告步驟執行之指令碼的標準輸出和標準錯誤。Image Builder 會將該輸出保留在元件日誌中。
當元件失敗時， 會將第一個失敗步驟的詳細資訊 AWS TOE 寫入主控台日誌，然後是該步驟的完整標準錯誤輸出。
```
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` 與 `componentFailure.componentArn` 報告的值相同，因此請使用它來比對日誌區塊與映像的失敗內容。 `Document` 是元件文件宣告`name`的 ，作者會獨立於元件資源選擇，因此兩者可以不同，而且無法`Document`單獨識別哪個元件失敗。
AWS TOE `Stderr`只有在失敗的步驟產生它們時， 才會寫入 `ErrorMessage`和 。
Image Builder 會在建置完成時將元件日誌串流至 Amazon CloudWatch Logs。如果您在基礎設施組態中指定了 Amazon S3 儲存貯體，Image Builder 也會在那裡寫入它們。如需日誌群組和串流名稱，請參閱 [使用 Amazon CloudWatch Logs 監控映像建置器日誌](monitor-cwlogs.md)。如需 AWS TOE 產生的檔案以及每個檔案包含的內容，請參閱 [元件記錄](toe-use-documents.md#component-logging)。
## 搭配 AI 代理器使用失敗內容
失敗內容旨在供自動化和人員讀取。疑難排解失敗建置的 AI 代理程式會讀取具名欄位，並使用其值做為其下次 API 呼叫的引數。這使得診斷可重複進行，並防止代理程式猜測要調查哪個元件或 。
您可以透過下列其中一種方式使用失敗內容：
+ **映像建置器中的故障診斷 AWS 管理主控台** - 故障診斷功能採用 AWS DevOps 代理程式，使用故障內容將其調查範圍限定為工作流程步驟和元件，該步驟和元件在檢查日誌和相關資源之前失敗。如需詳細資訊，請參閱[使用 AI 對失敗的建置進行故障診斷 - 預覽](devops-agent-troubleshooting.md)。
+ **您自己的 AI 編碼代理**程式 – 呼叫 的代理程式會在回應中`GetImage`接收失敗內容，並以相同方式遵循。若要為您的代理程式提供更廣泛的映像建置器知識，以針對其找到的內容採取行動，請參閱 [使用 AI 編碼代理程式對組建進行故障診斷](agent-toolkit-skill.md)。
如果您在失敗內容上建置自己的自動化，請將每個成員視為選用，並檢查您使用的成員，而不是`failureContext`其本身是否存在。Image Builder 傳回哪些成員取決於失敗，Image Builder 可以隨著時間新增成員。
## 考量事項
當您使用失敗內容時，請注意下列事項：
+ Image Builder 只會針對失敗的影像傳回失敗內容。一個成功的映像和您取消的映像沒有它。
+ 失敗的影像同時包含 `reason`和 `failureContext`。`reason` 使用 取得可讀取的失敗摘要，並`failureContext`找到它。
+ 如果元件使用 `ExecuteDocument`動作來執行巢狀文件，失敗內容會識別映像建置器從您的配方執行的元件，而不是巢狀文件。
+ 失敗內容中的錯誤訊息會限制長度，並且可以截斷。元件日誌會保留完整的輸出。
+ 失敗內容會報告失敗的第一個步驟。如果多個步驟失敗，請檢閱工作流程步驟執行和其餘的元件日誌。
+ 錯誤訊息可以包含元件或其他 AWS 服務產生的文字。如果您轉譯它們或將它們傳遞給另一個系統，請將它們視為不受信任的輸入。