本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 疑難排解映像建置器問題 EC2 Image Builder 與 整合 AWS 服務 ，以進行監控和疑難排解，以協助您疑難排解映像建置問題。Image Builder 會追蹤並顯示映像建置程序中每個步驟的進度。此外，Image Builder 可以將日誌匯出到您提供的 Amazon S3 位置。 對於進階故障診斷，您可以使用 Run Command [AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html)執行預先定義的命令和指令碼。 **Topics** + [管道建置疑難排解](#troubleshooting-pipelines) + [故障診斷方案](#image-builder-troubleshooting-scenarios) ## 管道建置疑難排解 如果 Image Builder 管道建置失敗，Image Builder 會傳回描述失敗的錯誤訊息。Image Builder 也會在失敗訊息`workflow execution ID`中傳回 ，例如下列範例輸出中的 ： ``` Workflow Execution ID: wf-12345abc-6789-0123-abc4-567890123abc failed with reason: … ``` Image Builder 透過為其標準映像建立程序中執行階段定義的一系列步驟，來安排和引導映像建置動作。程序的建置和測試階段各有相關聯的工作流程。當 Image Builder 執行工作流程來建置或測試新映像時，會產生工作流程中繼資料資源，以追蹤執行時間詳細資訊。 容器映像具有在分佈期間執行的額外工作流程。 **工作流程執行時間執行個體失敗的研究詳細資訊** 若要疑難排解工作流程的執行時間失敗，您可以使用 呼叫 [GetWorkflowExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowExecution.html) 和 [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowExecution.html) API 動作`workflow execution ID`。 **檢閱工作流程執行期日誌** + **Amazon CloudWatch Logs** Image Builder 會將詳細的工作流程執行日誌發佈至下列 Image Builder CloudWatch Logs 群組和串流： 使用 CloudWatch Logs，您可以使用篩選模式搜尋日誌資料。如需詳細資訊，請參閱《*Amazon CloudWatch Logs 使用者指南》中的*[使用篩選模式搜尋日誌資料](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SearchDataFilterPattern.html)。 + **AWS CloudTrail** 如果已在您的帳戶中啟用，則所有建置活動也會記錄在 CloudTrail 中。您可以依來源 篩選 CloudTrail 事件`imagebuilder.amazonaws.com`。或者，您可以搜尋執行日誌中傳回的 Amazon EC2 執行個體 ID，以查看管道執行的詳細資訊。 + **Amazon Simple Storage Service (S3)** 如果您已在基礎設施組態中指定 S3 儲存貯體名稱和金鑰字首，工作流程步驟執行期日誌路徑會遵循此模式： ``` S3://S3BucketName/KeyPrefix/ImageName/ImageVersion/ImageBuildVersion/WorkflowExecutionId/StepName ``` 您傳送至 S3 儲存貯體的日誌會顯示映像建置程序期間 EC2 執行個體上活動的步驟和錯誤訊息。日誌包含來自元件管理員的日誌輸出、已執行元件的定義，以及執行個體上所有步驟的詳細輸出 （以 JSON 為單位）。如果您遇到問題，您應該從 開始檢閱這些檔案`application.log`，以診斷執行個體上問題的原因。 根據預設，Image Builder 會關閉管道故障時正在執行的 Amazon EC2 建置或測試執行個體。您可以變更管道使用的基礎設施組態資源的執行個體設定，以保留您的建置或測試執行個體進行故障診斷。 若要變更主控台中的執行個體設定，您必須清除基礎設施組態資源**疑難排解設定**區段中**失敗時終止執行個體**核取方塊。 您也可以使用 中的 **update-infrastructure-configuration**命令來變更執行個體設定 AWS CLI。在命令參考的 JSON `false` 檔案中，使用 `--cli-input-json` 參數將 `terminateInstanceOnFailure`值設定為 。如需詳細資訊，請參閱[更新基礎設施組態](update-infra-config.md)。 ## 故障診斷方案 本節列出下列詳細的故障診斷案例： + [拒絕存取 – 狀態碼 403](#ts-access-denied) + [驗證建置執行個體上的 Systems Manager 代理程式可用性時，建置逾時](#ts-timeout-ssm-agent) + [Windows 次要磁碟在啟動時離線](#ts-win-disk-offline) + [建置失敗，CIS 強化基礎映像](#ts-cis-base) + [AssertInventoryCollection 失敗 (Systems Manager 自動化）](#ts-ssm-mult-inventory) 若要查看案例的詳細資訊，請選擇案例標題以展開案例。您可以同時展開多個標題。 ### 拒絕存取 – 狀態碼 403 #### Description 管道建置失敗，並顯示「AccessDenied：Access Denied 狀態碼：403」。 #### 原因 可能的原因包括： + 執行個體描述檔沒有存取 APIs或元件資源所需的[許可](set-up-ib-env.md#image-builder-IAM-prereq)。 + 執行個體描述檔角色缺少記錄到 Amazon S3 所需的許可。最常見的情況是，當執行個體描述檔角色沒有 S3 儲存貯體的 **PutObject** 許可時，就會發生這種情況。 #### 解決方案 視原因而定，可以解決此問題，如下所示： + **執行個體描述檔缺少受管政策** – 將缺少的政策新增至執行個體描述檔角色。然後再次執行管道。 + **執行個體描述檔缺少 S3 儲存貯體的寫入許可** – 將政策新增至執行個體描述檔角色，以授予 **PutObject** 寫入 S3 儲存貯體的許可。然後再次執行管道。 ### 驗證建置執行個體上的 Systems Manager 代理程式可用性時，建置逾時 #### Description 當步驟正在驗證目標執行個體 (s)'' 上的 Systems Manager 代理程式可用性時，管道建置失敗，並出現「狀態 = 'TimedOut'」和「失敗訊息 = '步驟逾時」。 #### 原因 可能的原因包括： + 啟動以執行建置操作和執行元件的執行個體無法存取 Systems Manager 端點。 + 執行個體描述檔沒有必要的[許可](set-up-ib-env.md#image-builder-IAM-prereq)。 #### 解決方案 根據可能的原因，可以解決此問題，如下所示： + **存取問題、私有子網路** – 如果您要在私有子網路中建置 ，請確定您已為 Systems Manager、Image Builder 設定 PrivateLink 端點，如果想要記錄，則為 Amazon S3/CloudWatch。如需設定 PrivateLink 端點的詳細資訊，請參閱[透過 存取 AWS 服務 AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-access-aws-services.html)。 + **缺少許可** – 將下列受管政策新增至 Image Builder 的 IAM 服務連結角色： + EC2InstanceProfileForImageBuilder + EC2InstanceProfileForImageBuilderECRContainerBuilds + AmazonSSMManagedInstanceCore 如需 Image Builder 服務連結角色的詳細資訊，請參閱 [使用映像建置器的 IAM 服務連結角色](image-builder-service-linked-role.md)。 ### Windows 次要磁碟在啟動時離線 #### Description 當用於建置映像建置器 Windows AMI 的執行個體類型與用於從 AMI 啟動的執行個體類型不符時，非根磁碟區在啟動時離線時可能會發生問題。這主要發生在建置執行個體使用比啟動執行個體更新的架構時。 下列範例示範在 EC2 Nitro 執行個體類型上建置映像建置器 AMI 並在 EC2 Xen 執行個體上啟動時會發生什麼情況： **組建執行個體類型**：m5.large (Nitro) **啟動執行個體類型**：t2.medium (Xen) ``` PS C:\Users\Administrator> get-disk Number Friendly Name Serial Number Health Status Operational Status Total Size Partition Style ------ ------------- ------------- ------------- ------------------ ---------- --------------- 0 AWS PVDISK vol0abc12d34e567f8a9 Healthy Online 30 GB MBR 1 AWS PVDISK vol1bcd23e45f678a9b0 Healthy Offline 8 GB MBR ``` #### 原因 由於 Windows 預設設定，新發現的磁碟不會自動上線並格式化。在 EC2 上變更執行個體類型時，Windows 會將此視為探索到的新磁碟。這是因為基礎驅動程式變更。 #### 解決方案 我們建議您在建置要啟動的 Windows AMI 時使用相同的執行個體類型系統。請勿在基礎設施組態中包含以不同系統建置的執行個體類型。如果您指定的任何執行個體類型使用 Nitro 系統，則它們都應該使用 Nitro 系統。 如需建置在 Nitro 系統上之執行個體的詳細資訊，請參閱《*Amazon EC2 使用者指南*》中的[建置在 Nitro 系統上之執行個體](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances)。 ### 建置失敗，CIS 強化基礎映像 #### Description 您正在使用 CIS 強化的基礎映像，而建置失敗。 #### 原因 當`/tmp`目錄分類為 時`noexec`，可能會導致映像建置器失敗。 #### 解決方案 在映像配方的 `workingDirectory` 欄位中，為您的工作目錄選擇不同的位置。如需詳細資訊，請參閱 [ImageRecipe](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageRecipe.html) 資料類型描述。 ### AssertInventoryCollection 失敗 (Systems Manager 自動化） #### Description Systems Manager Automation 在`AssertInventoryCollection`自動化步驟中顯示失敗。 #### 原因 您或您的組織可能已建立 Systems Manager State Manager 關聯，以收集 EC2 執行個體的庫存資訊。如果您的映像建置器管道已啟用增強型映像中繼資料收集 （這是預設值），映像建置器會嘗試為建置執行個體建立新的庫存關聯。不過，Systems Manager 不允許受管執行個體有多個庫存關聯，如果已存在，則可防止新的關聯。這會導致操作失敗，並導致管道建置失敗。 #### 解決方案 若要解決此問題，請使用下列其中一種方法關閉增強型影像中繼資料集合： + 在 主控台中更新您的映像管道，以清除**啟用增強型中繼資料收集**核取方塊。儲存變更並執行管道建置。 如需使用 EC2 Image Builder 主控台更新 AMI 映像管道的詳細資訊，請參閱 [從主控台更新 AMI 映像管道](update-image-pipeline-console.md)。如需使用 EC2 Image Builder 主控台更新容器映像管道的詳細資訊，請參閱 [從主控台更新容器映像管道](update-container-pipeline-console.md)。 + 您也可以使用 中的 **update-image-pipeline**命令來更新映像管道 AWS CLI。若要這樣做，請在 JSON 檔案中包含 `EnhancedImageMetadataEnabled` 屬性，並將 設定為 `false`。下列範例顯示 屬性設定為 `false`。 ``` { "name": "MyWindows2019Pipeline", "description": "Builds Windows 2019 Images", "enhancedImageMetadataEnabled": false, "imageRecipeArn": "arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03", "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration", "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration", "imageTestsConfiguration": { "imageTestsEnabled": true, "timeoutMinutes": 60 }, "schedule": { "scheduleExpression": "cron(0 0 * * SUN *)", "pipelineExecutionStartCondition": "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE" }, "status": "ENABLED" } ``` 為避免新管道發生這種情況，當您使用 EC2 Image Builder 主控台建立新管道時，請清除**啟用增強型中繼資料收集**核取方塊，或使用 建立管道`false`時，請將 JSON 檔案中的 `EnhancedImageMetadataEnabled` 屬性值設定為 AWS CLI。