為什麼我的影像建置管道發生故障，並在 Image Builder 中顯示錯誤訊息「Step timed out while step is verifying the Systems Manager Agent availability on the target instance(s)」(步驟在驗證目標執行個體上的 Systems Manager Agent 是否可用時發生逾時)？

簡短描述

EC2 Image Builder 使用 AWS Systems Manager Automation 來建立自訂影像。確保用於建立影像並執行測試的 Amazon EC2 執行個體可存取 AWS Systems Manager 服務。

由於以下原因，可能會出現錯誤訊息 failure message = 'Step timed out while step is verifying the SSM Agent availability on the target instance(s) (故障訊息 =「步驟在驗證目標執行個體上的 Systems Manager Agent 是否可用時發生逾時」)：

• 建置或測試執行個體無法存取 Systems Manager 端點。如要解決此問題，請檢查安全群組和網路存取控制清單 (network ACL) 的傳入及傳出規則。
• 執行個體設定檔沒有所需的許可。如要解決此問題，請驗證執行個體設定檔已附加正確的政策。
• 執行個體無法連接到執行個體中繼資料服務 (IMDS)。如要解決此問題，請驗證執行個體可以連接到 IMDS。
• 基礎影像上未安裝 AWS Systems Manager Agent (SSM Agent)。

解決方案

檢查您的安全群組和網路 ACL 的傳出和傳入規則

如果您的建置或測試執行個體無法存取 Systems Manager 端點，請檢查以下各項：

• 您的安全群組的傳出對連接埠 443 開放。
• 您的網路 ACL 的傳入對暫時連接埠 (1024–65535)，而它的傳出對連接埠 443 開放。

對於公有子網路建置：

• 子網路必須啟用 Enable auto-assign public IPv4 address。
• 路由表必須已連線至網際網路閘道。

對於私有子網路建置：

• 路由表必須有 NAT 閘道或執行個體，或連線到 Systems Manager (ssm、ssmmessages、ec2messages) 和 Image Builder 的 AWS PrivateLink 端點。如果已啟用日誌記錄，則路由表還必須有連線到 Amazon Simple Storage Service (Amazon S3) 或 Amazon CloudWatch 的端點。
• Amazon Virtual Private Cloud (Amazon VPC) 端點的安全群組必須允許連接埠 443 上的流量傳入到 VPC CIDR。

驗證執行個體設定檔具有正確的政策

執行個體設定檔是在基礎架構組態中定義的 AWS Identity and Access Management (IAM) 角色。如果它沒有必要許可，則建置將會失敗。執行個體設定檔必須已附加以下受管政策，才具有建置影像的許可：

• EC2InstanceProfileForImageBuilder
• EC2InstanceProfileForImageBuilderECRContainerBuilds (適用於 Docker 影像)
• AmazonSSMManagedInstanceCore

您還可以建立自訂政策，而且這些政策具有與上述受管政策類似的許可。

**注意：**請檢查角色的信任政策，確保允許 ec2.amazonaws.com 擔任該角色。

驗證執行個體可以連線至 IMDS

IMDS 用於存取來自執行中執行個體的中繼資料。如果您的執行個體無法連線至 IMDS，則建置將會失敗。確保您的作業系統 (OS) 的防火墻允許連接埠 80 上的流量 169.254.169.254，使執行個體可以連線至 IMDS。

執行下列命令來測試連線能力：

$ telnet 169.254.169.254 80

若您正使用代理，則請設定 SSM Agent 以便使用代理進行作業。對於 Linux，請見設定 SSM Agent 以使用代理 (Linux)。對於 Microsoft Windows，請見將 SSM Agent 設定為使用 Windows Server 執行個體的代理。

驗證已在基礎影像上安裝 SSM Agent

映像產生器用來建置映像檔和執行測試的執行個體必須已安裝 Systems Manager Agent。

Linux

對於沒有 SSM 代理程式的 Amazon EC2 Linux 執行個體，映像產生器預設會在建置執行個體上安裝 SSM 代理程式。不過，如果您在配方中提供使用者資料，則您也必須確定 SSM 代理程式已安裝在基礎映像上。或者，使用您的使用者資料輸入來安裝 SSM 代理程式。

Windows

映像產生器不會在適用於 Windows 伺服器的 Amazon EC2 建置執行個體上安裝 SSM 代理程式。如要檢查基礎影像上是否已預先安裝 SSM 代理程式，請使用基礎影像啟動 Amazon EC2 執行個體。然後，在 PowerShell 中運行以下命令：

Get-Service AmazonSSMAgent

如果您的基本映像上未預先安裝 SSM 代理程式，則您必須從來源映像檔啟動執行個體。接下來，在 EC2 執行個體上手動安裝 SSM 代理程式，然後從執行個體建立新的基礎映像。

關閉「在失敗時終止執行個體」

若上述解決方案未能解決問題，則請：

1.    打開 EC2 Image Builder 主控台。

2.    在 Infrastructure configuration（基礎結構組態）下，啟用 Terminate instance on failure（失敗時終止執行個體），然後再次執行管道。

3.    連線至執行個體並執行以下命令，以便驗證與 Systems Manager 端點的連線狀況：

Linux 執行個體

$ curl -v https://ssm.region.amazonaws.com

$ curl -v https://ec2messages.region.amazonaws.com

$ curl -v https://ssmmessages.region.amazonaws.com

Windows 執行個體

Test-NetConnection ssm.region.amazonaws.com -port 443

Test-NetConnection ec2messages.region.amazonaws.com -port 443

Test-NetConnection ssmmessages.region.amazonaws.com -port 443

**注意：**用您的 AWS 區域取代 region。

4.    使用下列路徑來檢查 SSM 日誌中的任何故障或錯誤的 ：

Linux

• /var/log/amazon/ssm/amazon-ssm-agent.log
• /var/log/amazon/ssm/errors.log

Windows

• %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log
• %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

---