如何對 Image Builder 中的建置管道逾時錯誤進行疑難排解？

解決方法

**注意：**如果您在執行 AWS Command Line Interface (AWS CLI) 命令時收到錯誤訊息，請參閱對 AWS CLI 錯誤進行疑難排解。此外，請確定您使用的是最新的 AWS CLI 版本。

若要疑難排解建置管道逾時錯誤，請根據逾時發生的時間採取以下動作。如需有關如何監控逾時的資訊，請參閱使用 Amazon CloudWatch Logs 監控 Image Builder 日誌。

建置在驗證 SSM Agent 可用性時發生逾時

如果逾時發生在建置驗證 AWS Systems Manager Agent (SSM Agent) 時，您可能會收到以下其中一則錯誤訊息：

「Workflow Execution ID: failed with reason: ExpectationNotMet. ssm:*CommandInvocations returned terminal state Failed in workflow step LaunchBuildInstance.」

「Workflow Execution ID: failed with reason: An error occurred (InvalidInstanceId) when calling the SendCommand operation: Instances [[i-1a1b1c1d1e1f1g1h1]] not in a valid state for account in workflow step LaunchBuildInstance.」

「Workflow Execution ID: failed with reason: ExpectationNotMet. ec2:DescribeInstanceStatus did not meet terminal states: [['passed']] after 100 attempts.Reason: Timeout. in workflow step LaunchBuildInstance.」

若要疑難排解這些錯誤，請採取以下動作。

驗證 Amazon EC2 執行個體具有所需的 IAM 權限

請確認您的 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體具有所需的 AWS Identity and Access Management (IAM) 權限。將 AmazonSSMManagedInstanceCore 受管政策連接到您用於 Image Builder 的 IAM 角色。若要識別您用於 Image Builder 的角色，請查看基礎結構組態詳細資訊。另外，也請確認 AWSServiceRoleForImageBuilder 角色可以使用映像配方區塊裝置上指定的 AWS Key Management Service (AWS KMS) 金鑰。

確認 SSM Agent 可以連線到端點

請根據您的組態檢查以下設定：

• 如果您使用具有網際網路閘道的公共子網路，請將該子網路設定為自動指派公共 IPv4 位址。
• 如果您使用具有 NAT 閘道的私有子網路，請將 NAT 閘道設定為使用公共子網路。
• 如果您使用具有 Amazon Virtual Private Cloud (Amazon VPC) 端點的私有子網路，請為 AWS Systems Manager 設定私有端點。
• 確認安全群組和網路存取控制清單 (網路 ACL) 允許在臨時連接埠 1024-65535 上進行傳入連線，並允許在連接埠 443 上進行傳出連線。
• 如果您使用具有 AWS PrivateLink 端點的私有子網路，請確認 Amazon VPC 端點的安全群組允許在連接埠 443 上進行傳入連線。
  **注意：**若要允許傳入連線，請使用子網路或 Amazon VPC CIDR 位址。

如需更多疑難排解步驟，請參閱為什麼我的映像建置管道在 Image Builder 中失敗，並顯示「Step timed out while step is verifying the Systems Manager Agent availability on the target instance(s)」錯誤？

建置在下載 AWS CLI 時發生逾時

如果 EC2 執行個體的 Amazon Machine Image (AMI) 沒有 AWS CLI，則 bootstrap 指令碼會透過網際網路安裝 AWS CLI。但是，如果您在不允許網際網路連線的私有子網路上建置，則建置會在 ApplyBuildComponents 步驟逾時。對於容器建置，逾時會發生在 BootstrapBuildInstance 步驟。

若要解決此逾時問題，請透過 NAT 閘道或網際網路閘道允許子網路連線到網際網路。或者，建立已安裝 AWS CLI 的自訂 AMI。

逾時發生在 LaunchBuildInstance 步驟

您必須在建置執行個體中使用唯一的根裝置名稱。因此，將您的根裝置命名為 /dev/xvda 或 /dev/sda1 並非最佳實務。如果您在使用 CreateImageRecipe API 時使用重複的根裝置名稱，則會收到包含以下錯誤訊息的逾時：

「Workflow Execution ID: failed with reason: ExpectationNotMet. ec2:DescribeInstanceStatus did not meet terminal states: [['passed']] after 100 attempts.Reason: Timeout. in workflow step LaunchBuildInstance.」

**注意：**如果您使用的是建置於 AWS Nitro System 上的執行個體，或 Xen 執行個體類型，則可以使用重複的裝置名稱。

若要檢查來源 AMI 的裝置名稱，請執行以下 describe-images AWS CLI 命令：

aws ec2 describe-images \
    --region exampleregion \
    --image-ids exampleami

**注意：**將 exampleregion 替換為您的 AWS 區域，並將 exampleami 替換為來源 AMI ID。

在輸出中，檢查 RootDeviceName 的值。請確認您在 Image Builder 方案中使用相同的裝置名稱。

建置在取得 Image Builder 元件時發生逾時

如果您在私有子網路上建置，而且 Image Builder 無法連線以下載元件，那麼您會收到以下錯誤訊息：

「failed with reason: failed to download the EC2 Image Builder Component, operation error imagebuilder: GetComponent, exceeded maximum number of attempts, 3, dial tcp i/o timeout.」

若要解決前述錯誤，請確認您的安全群組和 DNS 解析允許在所需連接埠上通訊。或者，請為您在 Image Builder 基礎結構組態中使用的相同 VPC 和子網路建立介面 Amazon VPC 端點。另外，請確認您的組態符合 Image Builder 要求。

建置在擷取 mirrorlist 時發生逾時

Amazon Linux 會將 mirrorlist 儲存在 Amazon Simple Storage Service (Amazon S3) 儲存貯體中。如果您在無法存取 Amazon S3 的私有子網路上建置，則會收到以下逾時錯誤訊息：

「Could not retrieve mirrorlist; error was 12: Timeout was reached.」

若要解決此問題，請為 Amazon S3 建立 Amazon VPC 閘道端點。預設情況下，當您建立端點時，Amazon VPC 會將 Amazon S3 首碼清單新增至路由表。但是，最佳實務是確認首碼清單位於路由表中。

如果您在非 Amazon Linux 的 AMI 上建置，則 mirrorlist 不會儲存在 Amazon S3 上。在此情況下，建置在取得 repository/mirrorlist 時可能會發生逾時。請確認您在網路防火牆或 Proxy 中允許儲存庫位址或網址。如果 repository/mirrorlist 需要網際網路，請透過 NAT 閘道允許子網路連線到網際網路。

逾時發生在 ApplyBuildComponents 步驟

如果建置逾時發生在 ApplyBuildComponents 步驟，那麼您會收到以下錯誤訊息：

「Workflow Execution ID: failed with reason: ExpectationNotMet. ssm:ListCommandInvocations did not meet terminal states: [['Success']] after 1440 attempts.Reason: Timeout. in workflow step ApplyBuildComponents.」

若要疑難排解此問題，請分析 Image Builder 傳送到基礎結構 Amazon S3 儲存貯體的日誌。如需更多資訊，請參閱管道建置疑難排解中的檢閱工作流程執行時期日誌。

另外，也請分析您用來建置或測試新映像之執行個體的元件日誌。在您檢查日誌之前，請停用失敗時終止執行個體。若要存取此功能，請完成以下步驟：

1. 開啟 Image Builder console (Image Builder 主控台)。
2. 選擇 Edit infrastructure (編輯基礎結構)。
3. 選擇 Edit (編輯)，然後選取 Specify settings to troubleshoot issues with building your image (指定設定以疑難排解建置映像時的問題)。
4. 選擇 Instance settings (執行個體設定)，然後清除 Terminate instance on failure (失敗時終止執行個體)。

**注意：**detailedoutput.json 日誌檔描述元件失敗或逾時的原因。application.log 檔案會提供偵錯層級的疑難排解資訊。

最後，請檢查文件的 YAML 結構描述中的 timeoutSeconds 參數值。預設值為 7200。若要增加 Image Builder 逾時前的時間長度，請更新 YAML 文件中的值。值為 -1 表示無限大。