ECS CannotPullContainerError の原因と解決策

概要

CannotPullContainerError は、AWS ECSタスクがコンテナイメージをプルできない場合に発生するエラーです。ECRやDocker Hubからイメージを取得する際の認証、ネットワーク、権限の問題が主な原因です。

エラーメッセージ

CannotPullContainerError: Error response from daemon: pull access denied for 123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/my-app, repository does not exist or may require 'docker login'

CannotPullContainerError: Error response from daemon: manifest for my-image:latest not found: manifest unknown: manifest unknown

ResourceInitializationError: unable to pull secrets or registry auth: execution resource retrieval failed: unable to retrieve ecr registry auth

原因

1. ECRへのアクセス権限不足

タスク実行ロールにECRへのアクセス権限がありません。

1
2
3
4
5
// 必要な権限がない場合
{
  "taskExecutionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
}
// このロールにecr:GetAuthorizationToken等がない

2. イメージが存在しない

1
2
3
# イメージ名やタグが間違っている
123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/my-app:v1.0.0
# → 実際はmy-app:v1.0.1が最新

3. ネットワーク設定の問題

プライベートサブネットからECRにアクセスできない場合です。

4. クロスアカウントのECRアクセス

別アカウントのECRリポジトリにアクセス権限がない場合です。

5. Docker Hub レート制限

Docker Hubのプルレート制限に達した場合です。

解決策

1. タスク実行ロールにECR権限を追加

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

または、マネージドポリシーをアタッチ：

1
2
3
aws iam attach-role-policy \
  --role-name ecsTaskExecutionRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

2. イメージの存在確認

1
2
3
4
5
6
7
8
9
# ECRイメージ一覧
aws ecr describe-images \
  --repository-name my-app \
  --region ap-northeast-1

# 特定タグの確認
aws ecr describe-images \
  --repository-name my-app \
  --image-ids imageTag=v1.0.0

3. ネットワーク設定（プライベートサブネット）

VPCエンドポイントを作成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# ECR API エンドポイント
aws ec2 create-vpc-endpoint \
  --vpc-id vpc-xxx \
  --service-name com.amazonaws.ap-northeast-1.ecr.api \
  --vpc-endpoint-type Interface \
  --subnet-ids subnet-xxx

# ECR DKR エンドポイント
aws ec2 create-vpc-endpoint \
  --vpc-id vpc-xxx \
  --service-name com.amazonaws.ap-northeast-1.ecr.dkr \
  --vpc-endpoint-type Interface \
  --subnet-ids subnet-xxx

# S3 エンドポイント（イメージレイヤー用）
aws ec2 create-vpc-endpoint \
  --vpc-id vpc-xxx \
  --service-name com.amazonaws.ap-northeast-1.s3 \
  --vpc-endpoint-type Gateway \
  --route-table-ids rtb-xxx

4. クロスアカウントECRアクセス

リポジトリポリシーを設定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCrossAccountPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::987654321098:root"
      },
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:BatchCheckLayerAvailability"
      ]
    }
  ]
}

5. Docker Hub認証情報の設定

Secrets Managerにクレデンシャルを保存：

1
2
3
aws secretsmanager create-secret \
  --name dockerhub-credentials \
  --secret-string '{"username":"myuser","password":"mytoken"}'

タスク定義で参照：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "containerDefinitions": [
    {
      "name": "my-container",
      "image": "myuser/my-image:latest",
      "repositoryCredentials": {
        "credentialsParameter": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:dockerhub-credentials"
      }
    }
  ]
}

6. Fargate の場合

パブリックサブネット + パブリックIP自動割り当て、または NAT Gateway が必要：

1
2
3
4
5
6
7
8
9
{
  "networkConfiguration": {
    "awsvpcConfiguration": {
      "subnets": ["subnet-xxx"],
      "securityGroups": ["sg-xxx"],
      "assignPublicIp": "ENABLED"
    }
  }
}

デバッグ手順

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# 1. タスク停止理由を確認
aws ecs describe-tasks \
  --cluster my-cluster \
  --tasks arn:aws:ecs:...:task/xxx

# 2. サービスイベントを確認
aws ecs describe-services \
  --cluster my-cluster \
  --services my-service

# 3. ローカルでイメージプルをテスト
aws ecr get-login-password | docker login --username AWS --password-stdin 123456789012.dkr.ecr.ap-northeast-1.amazonaws.com
docker pull 123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/my-app:latest

# 4. タスク実行ロールの権限確認
aws iam list-attached-role-policies --role-name ecsTaskExecutionRole

ECS CannotPullContainerError

概要