在ECS上启动EC2类型任务时Amazon ECR镜像无法下载求助

针对你遇到的ECS任务卡在启动中、未拉取ECR镜像最终失败的情况，按以下步骤逐一排查：

• 验证ECS实例的IAM角色权限
  ECS实例必须具备拉取ECR镜像的权限，确保实例关联的IAM角色包含ecr:GetDownloadUrlForLayer、ecr:BatchGetImage、ecr:BatchCheckLayerAvailability这三个核心权限。默认的AmazonEC2ContainerServiceforEC2Role角色已包含这些权限，若使用自定义角色，需检查权限策略是否覆盖。
  可通过CLI查询实例关联的IAM角色：

  aws ec2 describe-instances --instance-ids <你的实例ID> --query 'Reservations[0].Instances[0].IamInstanceProfile'
  

• 检查任务定义的镜像URI正确性
  确认任务定义中的镜像地址完全匹配ECR仓库的地址，格式应为[AWS账号ID].dkr.ecr.[区域].amazonaws.com/[仓库名]:[标签]，避免账号ID、区域、仓库名或标签拼写错误。
  可直接在ECS实例上手动执行拉取命令测试：

  docker pull <你的镜像URI>
  

  若命令报错，可直接定位问题根源（如镜像不存在、权限不足）。

• 查看ECS Agent的详细日志
  常规系统日志未包含镜像拉取信息时，重点查看ECS Agent日志：

  • Amazon Linux 2：/var/log/ecs/ecs-agent.log
  • Amazon Linux 2023：/var/log/amazon/ecs/ecs-agent.log
    用任务ARN过滤日志，获取任务调度和镜像拉取的详细过程：

  grep -A 10 -B 5 "<你的任务ARN>" /var/log/ecs/ecs-agent.log
  

  日志中通常会明确记录未拉取镜像的原因，如权限错误、网络不通、镜像不存在等。

• 检查实例的网络连通性

  • 测试实例能否访问ECR端点：执行curl https://[AWS账号ID].dkr.ecr.[区域].amazonaws.com/v2/，若返回{"errors":[{"code":"UNAUTHORIZED","message":"authentication required"}]}，说明网络连通正常，问题出在权限；若无法连通，检查实例安全组、NACLs是否允许HTTPS（443端口）出站访问ECR服务。
  • 若实例位于私有子网，需确认已配置ECR接口端点和S3网关端点（ECR镜像层存储在S3中），否则私有子网实例无法访问公网ECR服务。

• 检查任务资源配置与实例剩余资源
  确认任务定义中的CPU、内存限制未超过ECS实例的剩余可用资源，若资源不足，ECS Agent会跳过任务调度，此类信息也会在ECS Agent日志中体现。

内容的提问来源于stack exchange，提问作者jasonbuehler