如何解決當我在 Amazon ECS 中啟動 EC2 任務時，收到「CannotPullContainerError」錯誤？

簡短說明

CannotPullContainerError 會因以下原因而發生：

• Amazon EC2 啟動類型任務因為您未正確設定網路，所以無法提取映像。
• AWS Identity and Access Management (IAM) 角色沒有提取映像的權限。
• 您已達到 DockerHub 速率配額。
• 您的映像名稱或標籤不存在。
• 您的任務定義參考位於不同 AWS 帳戶中的映像。
• 您的檔案系統已滿。

解決方法

使用 AWSSupport-TroubleshootECSTaskFailedToStart 執行手冊來進行疑難排解

若要對無法啟動的 Amazon ECS 任務進行疑難排解，請使用 AWSSupport-TroubleshootECSTaskFailedToStart 執行手冊。當您執行執行手冊時，必須使用最近失敗的任務 ID。如果失敗的任務是 Amazon ECS 服務的一部分，則請使用該服務中最近失敗的任務。失敗的任務在自動化期間必須可在 ECS:DescribeTasks 中看見。依預設，Amazon ECS 任務在進入 Stopped (已停止) 狀態後的 1 小時內可見。

若要啟動執行手冊，請參閱 AWSSupport-TroubleshootECSTaskFailedToStart。根據自動化的輸出，使用以下其中一種解決方法。

**重要：**請在 Amazon ECS 叢集資源所在的相同 AWS 區域中使用 AWSSupport-TroubleshootECSTaskFailedToStart 執行手冊。

您的 Amazon ECS 容器執行個體網路組態不正確

如果您的 Amazon ECS 容器執行個體沒有網際網路連線，則執行個體無法連線至 Amazon Elastic Container Registry (Amazon ECR) 端點。如果未連線至端點，執行個體就無法提取映像。若要驗證您的 Amazon ECS 容器執行個體具有網際網路存取權，請採取以下動作：

• 確認您的執行個體可透過網際網路閘道或 NAT 閘道存取網際網路。若要對 NAT 閘道連線問題進行疑難排解，請參閱為什麼我無法使用 NAT，將私有子網路中的 EC2 執行個體連線至網際網路？
  **注意：**您可以使用 AWS PrivateLink 來取代 NAT 閘道。若要避免錯誤，請務必正確設定 PrivateLink。
• 確認您已在執行個體、安全群組和網路存取控制清單 (網路 ACL) 層級，允許透過連接埠 443 進行傳入 HTTPS 存取。若要對網際網路閘道連線問題進行疑難排解，請參閱為什麼我的 Amazon EC2 執行個體無法透過網際網路閘道存取網際網路？
• 如果您使用虛擬私有雲端 (VPC) 端點連線至 Amazon ECR 端點，則請檢查您的 Amazon ECS 容器執行個體安全群組。允許您的 Amazon ECS 容器執行個體將流量傳送至您 VPC 端點的安全群組。
• 如果您收到錯誤訊息 CannotPullContainerError: API error，則請參閱如何解決無法從 Amazon ECR 提取映像的 Amazon ECS 任務？

您的 IAM 角色沒有提取映像的權限

確認與執行個體設定檔相關聯的執行個體 IAM 角色具有存取 Amazon ECR 儲存庫的權限。

注意：AmazonEC2ContainerRegistryReadOnly AWS 受管政策提供提取映像所需的最低權限。

您已達到 DockerHub 提取速率配額

如果您嘗試從 DockerHub 提取映像，且已達到提取速率配額，則會收到以下錯誤：

「CannotPullContainerError: inspect image has been retried 5 time(s): httpReaderSeeker: failed open: unexpected status code https://registry-1.docker.io/v2/manifests/sha256:2bb501e6429 Too Many Requests - Server message: toomanyrequests:」

若要解決此問題，請參閱如何解決 Amazon ECS 中的錯誤「CannotPullContainerError: You have reached your pull rate limit」？

您的映像名稱或標籤不存在

如果您定義了託管在 Amazon ECR 中的映像或標籤，但該映像或標籤不存在，則會收到以下錯誤：

「Cannotpullcontainererror: pull image manifest has been retried 1 time(s): failed to resolve ref 123456789.dkr.ecr.ap-southeast-2.amazonaws.com/image-name:tag: 123456789**.dkr.ecr.ap-southeast-2.amazonaws.com/image-name:tag: not found**」

若要解決此問題，請確認您的任務定義中映像欄位的值是否正確。確認您要從中提取的容器登錄檔中存在相應的儲存庫和標籤。

如果您的任務從 Amazon ECR 以外的登錄檔提取映像，且任務缺少資訊，則會收到不同的錯誤。當映像不存在、標籤不存在，或您未提供登錄檔憑證時，會發生以下錯誤：

「Cannotpullcontainererror: pull image manifest has been retried 1 time(s): failed to resolve ref docker.io/library/invalid-name:non-existenttag: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed」

若要解決此問題，請檢查任務定義中的映像欄位。確認映像存在於對應的容器登錄檔中。如果映像存在，請務必提供正確的憑證。如需更多資訊，請參閱在 Amazon ECS 中使用非 AWS 容器映像。

任務定義中參考的映像位於不同帳戶

如果您的映像位於不同的帳戶中，則您可能會收到以下錯誤：

「Cannotpullcontainererror: pull access denied for 123456789***.dkr.ecr.us-east-1.amazonaws.com/image-name:tag, repository does not exist or may require 'docker login': denied: User: arn:aws:sts::012345678**:assumed-role/role-name/ec2 instance id is not authorized to perform: ecr:BatchGetImage on resource: arn:aws:ecr:us-east-1:123456789*:repository/image-name:tag because no resource-based policy allows the ecr:BatchGetImage action」

若要解決此問題，您必須在映像所在帳戶的儲存貯體政策中允許 ecr:batchGetImage 動作。

例如，與 Amazon ECS 叢集關聯的執行個體位於帳戶 A 中，而任務定義參考帳戶 B 中的映像。帳戶 B 中的儲存庫政策必須允許帳戶 A 中的執行個體 IAM 角色使用 ecr:batchGetImage。您還必須在儲存庫政策中啟動跨帳戶權限。然後，確認帳戶 A 中的執行個體可以從帳戶 B 提取映像。如需更多資訊，請參閱如何允許次要帳戶在我的 Amazon ECR 映像儲存貯體中推送或提取映像？

您的檔案系統已滿

如果您的檔案系統已滿，您將收到以下錯誤：

「CannotPullContainerError: write /var/lib/docker/tmp/GetImageBlob2923440728: no space left on device」

若要解決此問題，請採取以下動作：

• 設定自動 Amazon ECS 任務和映像清理。
• 增加容器執行個體的磁碟大小。