How can I resolve the Amazon ECR error "CannotPullContainerError: API error" in Amazon ECS?

5 minute read
0

If I pull images with Amazon Elastic Container Registry (Amazon ECR), I get the following error: "CannotPullContainerError: API error."

Short description

You can receive this error due to one of the following issues:

  • Your launch type doesn't have access to the Amazon ECR endpoint
  • Your Amazon ECR repository policy restricts access to repository images
  • Your AWS Identity and Access Management (IAM) role doesn't have the right permissions to pull or push images
  • The image can't be found
  • Amazon Simple Storage Service (Amazon S3) access is denied by your Amazon Virtual Private Cloud (Amazon VPC) gateway endpoint policy

To pull images, Amazon ECS must communicate with the Amazon ECR endpoint.

To troubleshoot the errors for Amazon ECS tasks that fail to start, use the AWSSupport-TroubleshootECSTaskFailedToStart runbook. Then, refer to the relevant troubleshooting steps for your issue.

Resolution

Important:

  • Use the AWSSupport-TroubleshootECSTaskFailedToStart runbook in the same AWS Region where your ECS cluster resources are located.
  • When using the runbook, you must use the most recently failed Task ID. If the failed task is part of an Amazon ECS service, then use the most recently failed task in the service. The failed task must be visible in ECS:DescribeTasks during the automation. By default, stopped ECS tasks are visible for 1 hour after entering the Stopped state. Using the most recently failed task ID prevents the task state cleanup from interrupting the analysis during the automation.

For instructions on how to initiate the runbook, see AWSSupport-TroubleshootECSTaskFailedToStart. Based on the output of the automation, use one of the following manual troubleshooting steps.

Your launch type doesn't have access to the Amazon ECR endpoint

1.    You might be running a task with an Amazon Elastic Compute Cloud (Amazon EC2) launch type and your container instance is in a private subnet. Or, you might be running a task with the AWS Fargate launch type in a private subnet. In either of these cases, confirm that your subnet has a route to a NAT gateway in the route table.

2.    If your task has an EC2 launch type and your container instance is in a public subnet, the instance must have a public IP address.

-or-

If you're running a task with the Fargate launch type in a public subnet, then choose ENABLED for Auto-assign public IP when you launch it. This allows your task to have outbound network access to pull an image.

3.    Configure the NAT gateway in your VPC to route requests to the internet.
Note: You can use AWS PrivateLink as an alternative to a NAT gateway.

4.    If you're using AWS PrivateLink for Amazon ECR, then check the configuration for the security group that's associated with the VPC endpoints for Amazon ECR. You must allow inbound traffic over HTTPS (port 443) from within the security group of your VPC CIDR, container instance, or Fargate task or service.

5.    Confirm that the security group attached to your instance and Fargate task allows the following outbound access: HTTPS on port 443 DNS (UDP and TCP) on port 53 Your subnet's network access control list (network ACL).

Your Amazon ECR repository policy restricts access to repository images

Check your Amazon ECR repository policy for restrictions on accessing the repository. The following repository policy example allows IAM users to push and pull images:

{  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPushPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::123456789012:user/push-pull-user-1",
          "arn:aws:iam::123456789012:user/push-pull-user-2"
        ]
      },
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:BatchCheckLayerAvailability",
        "ecr:PutImage",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload"
      ]
    }
  ]
}

Your IAM role doesn't have the right permissions to pull images

If you're running a task with an EC2 launch type, then check the permissions for the instance IAM role that's associated with the instance profile. It must have permissions to access the Amazon ECR repository.

Note: The AWS managed policy AmazonEC2ContainerRegistryReadOnly provides the minimum permissions required to pull images.

If you're running a task with a Fargate launch type, then confirm that the AmazonECSTaskExecutionRolePolicy has the required permissions.

The image can't be found

To confirm the correct image name in the URI, check the image parameter in the container definitions section of your task definition.

Note: To pull by tag, use the following image name format: registry/repository[:tag]. To pull by digest, use the registry/repository[@digest] format.

Amazon S3 access is denied by your Amazon VPC gateway endpoint policy

If you have a route to an Amazon VPC gateway endpoint for Amazon S3 in the route table, then complete the following steps:

1.    Verify the access policy of the Amazon VPC gateway endpoint.

2.    Confirm that the Amazon VPC gateway endpoint has the correct policy to access the S3 bucket.

Related information

CannotPullContainer task errors