AWS Containers Advent Calendar 2025

AWS Fargate のコンテナイメージプルを完全理解：実行ロールとネットワーク経路の設定ガイド

Posted at 2025-12-13

概要

AWS Fargate でコンテナを起動する際、イメージプルに必要な「タスク実行ロール」の権限設定と、プライベート環境でのVPCエンドポイント構成を詳しく解説します。よくあるエラーの原因と対処法も具体的に紹介します。

1. Fargateのイメージプルの仕組み

Fargateでコンテナを起動する際、タスクがRUNNING状態になる前に必ずイメージのプル処理が行われます。この処理で重要なのが「タスク実行ロール（Execution Role）」です。

【挿絵候補】：Fargateタスク起動時のイメージプルフロー図（シーケンス図、Fargate→タスク実行ロール→ECR API/DKR→S3の流れ、認証トークン取得からレイヤーダウンロードまでの時系列を表現、PlantUMLまたはmermaid推奨）

タスクロールとの違い

多くの方が混同しがちなのが、以下の2つのロールです：

ロールの種類	用途	使用タイミング
タスク実行ロール（Execution Role）	イメージプル、ログ出力などのインフラ操作	タスク起動時
タスクロール（Task Role）	アプリケーションからのAWSサービスへのアクセス	コンテナ実行中

例えるなら、タスク実行ロールは「引越し業者がトラックで荷物を運ぶための免許証」、タスクロールは「新居に入居した後に使う家の鍵」のようなものです。

認証フローの詳細

イメージプルは以下の手順で実行されます：

認証トークンの取得：タスク実行ロールでecr:GetAuthorizationTokenを呼び出し
レイヤー情報の取得：取得したトークンでイメージのマニフェストとレイヤー情報を確認
レイヤーのダウンロード：S3経由でイメージレイヤーをダウンロード
初期セットアップ：CloudWatch Logsへのストリーム作成など

この処理が失敗すると、タスクはResourceInitializationError（多くの場合CannotPullContainerError）でSTOPPED状態になります。

2. タスク実行ロールに必要な権限

Amazon ECRを使用する場合

最小限必要な権限は以下の通りです：

{
  "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": "arn:aws:logs:ap-northeast-1:123456789012:log-group:/ecs/*"
    }
  ]
}

実務での推奨設定：AWS管理ポリシーAmazonECSTaskExecutionRolePolicyをアタッチするのが最も簡単です。このポリシーには上記の権限が含まれています。

他のプライベートレジストリを使用する場合

Docker Hubやプライベートレジストリからイメージをプルする場合、Secrets Managerに保存した認証情報へのアクセス権限が追加で必要です：

{
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue"
  ],
  "Resource": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:docker-hub-credentials-*"
}

シークレットがKMSで暗号化されている場合は、kms:Decrypt権限も必要です。

3. ネットワーク経路の設定

パブリックサブネット or NATゲートウェイ経由の場合

パブリックIPを持つタスクや、プライベートサブネット＋NATゲートウェイ構成の場合、特別な設定は不要です。インターネット経由でECRやDocker Hubへアクセスできます。

フルプライベート環境の場合

セキュリティ要件でインターネット接続を持たない環境では、VPCエンドポイントの設定が必須です。

必要なVPCエンドポイント

エンドポイント	タイプ	用途
com.amazonaws.ap-northeast-1.ecr.api	Interface	ECR APIへのアクセス
com.amazonaws.ap-northeast-1.ecr.dkr	Interface	Dockerレジストリへのアクセス
com.amazonaws.ap-northeast-1.s3	Gateway	イメージレイヤーの取得
com.amazonaws.ap-northeast-1.logs	Interface	CloudWatch Logsへの出力（オプション）
com.amazonaws.ap-northeast-1.secretsmanager	Interface	認証情報の取得（他レジストリ使用時）

セキュリティグループの設定

VPCエンドポイント用のセキュリティグループには、Fargateタスクからの443/TCPを許可する必要があります：

インバウンドルール:
- タイプ: HTTPS
- プロトコル: TCP
- ポート: 443
- ソース: <Fargateタスクのセキュリティグループ>

4. レジストリ別の設定方法

Amazon ECRの場合

タスク定義でのイメージ指定例：

{
  "family": "sample-app",
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "app",
      "image": "123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/my-app:latest",
      "memory": 512,
      "cpu": 256
    }
  ]
}

repositoryCredentialsの指定は不要です。タスク実行ロールの権限で自動的に認証されます。

Docker Hubやプライベートレジストリの場合

まず、Secrets Managerにシークレットを作成します：

aws secretsmanager create-secret \
  --name docker-hub-credentials \
  --secret-string '{"username":"myuser","password":"mypassword"}' \
  --region ap-northeast-1

タスク定義でrepositoryCredentialsを指定：

{
  "containerDefinitions": [
    {
      "name": "app",
      "image": "docker.io/myuser/my-app:latest",
      "repositoryCredentials": {
        "credentialsParameter": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:docker-hub-credentials-AbCdEf"
      }
    }
  ]
}

5. よくある失敗パターンと対処法

エラー1: 「unable to pull secrets or registry auth」

原因：

タスク実行ロールにecr:GetAuthorizationToken権限がない
他レジストリ使用時にsecretsmanager:GetSecretValue権限がない
repositoryCredentialsの指定漏れ

対処法：
タスク実行ロールに必要な権限を追加します。ECRの場合はAmazonECSTaskExecutionRolePolicyをアタッチするのが確実です。

エラー2: タイムアウトや接続エラー

原因：

プライベートサブネットでNATゲートウェイもVPCエンドポイントもない
VPCエンドポイントのセキュリティグループで443/TCPが許可されていない

対処法：
VPCエンドポイント（ecr.api、ecr.dkr、s3）を作成し、セキュリティグループの設定を確認します。以下のコマンドでエンドポイント作成：

# ECR APIエンドポイント
aws ec2 create-vpc-endpoint \
  --vpc-id vpc-xxxxx \
  --vpc-endpoint-type Interface \
  --service-name com.amazonaws.ap-northeast-1.ecr.api \
  --subnet-ids subnet-xxxxx subnet-yyyyy \
  --security-group-ids sg-xxxxx \
  --region ap-northeast-1

エラー3: クロスアカウントECRのアクセス失敗

原因：
ECRリポジトリポリシーで実行アカウントへのpull権限が付与されていない

対処法：
リポジトリポリシーを更新します：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCrossAccountPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::999999999999:root"
      },
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ]
    }
  ]
}

イメージの更新取得について

デフォルトでは、Fargateはローカルキャッシュにイメージがなければプルします。常に最新イメージを取得したい場合は、タスク定義でimagePullBehaviorをALWAYSに設定します（プラットフォームバージョン1.4.0以降）：

{
  "containerDefinitions": [
    {
      "name": "app",
      "image": "...",
      "imagePullBehavior": "ALWAYS"
    }
  ]
}

6. 終わりに

Fargateのイメージプル問題は、「タスク実行ロールの権限」と「レジストリまでのネットワーク経路」の2つを押さえることで、ほとんどのケースが解決できます。

特にプライベート環境では、VPCエンドポイント（ecr.api、ecr.dkr、s3）の設定が必須です。セキュリティグループで443/TCPを許可することも忘れないようにしましょう。

次のステップとしては、以下を検討してみてください：

ECRのライフサイクルポリシーで古いイメージを自動削除
イメージスキャンを有効化してセキュリティ脆弱性を検出
AWS Copilotを使った簡易デプロイの実践

7. 参考文献・参考サイト

「Amazon ECS タスク実行 IAM ロール」AWS Documentation, https://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/task_execution_IAM_role.html
「Amazon ECS タスクのプライベートレジストリの認証」AWS Documentation, https://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/private-auth.html
「AWS Fargate での Amazon ECS のタスクネットワーキング」AWS Documentation, https://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/fargate-task-networking.html
「Amazon ECR インターフェイス VPC エンドポイント（AWS PrivateLink）」AWS Documentation, https://docs.aws.amazon.com/ja_jp/AmazonECR/latest/userguide/vpc-endpoints.html
「Amazon ECS トラブルシューティング」AWS Documentation, https://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/troubleshooting.html

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up