はじめに

Amazon ECS Fargate を使ってアプリケーションをデプロイする際、コンテナイメージの取得に失敗し CannotPullContainerError が発生することがあります。

このエラーは、ECS が ECR（Elastic Container Registry）からコンテナイメージを pull できないときに起きるものです。

この記事では、エラーの原因と対処法を自分用に整理しておきます。

書こうと思ったきっかけ

友達との開発で ECS + Fargate を使ったアプリケーションのデプロイを行っていた際、このエラーで5分以上足止めをくらいました。

個人の備忘録程度の走り書きとなっておりますが、温かい目で見守っていただければ幸いです。

単純な push の漏れや tag の不一致が原因だったので、今後同じことを繰り返さないよう備忘録として残します。

エラー内容

Amazon ECS Fargate でタスクを実行した際に、以下のようなエラーが発生することがあります：

CannotPullContainerError: pull image manifest has been retried 1 time(s):
failed to resolve ref xxx.dkr.ecr.ap-northeast-1.amazonaws.com/reverse-proxy-django-nginx:latest: not found

同様のエラーが reverse-proxy-django-app:latest についても発生している場合、以下の原因が考えられます。

主な原因

ECRにイメージが存在しない
指定されたリポジトリに latest タグの付いたイメージが存在しない
Docker push を忘れている
ビルド後に ECR への push をしていない
リポジトリ名の誤り
ECS のタスク定義で指定している名前が間違っている
タグ名のミスマッチ
latest ではなく v1.0.0 などのタグしか存在しない

対処方法

1. ECR の確認

AWS CLI または AWS コンソールで、以下のコマンドで確認します：

aws ecr describe-images \
  --repository-name reverse-proxy-django-nginx \
  --region ap-northeast-1

aws ecr describe-images \
  --repository-name reverse-proxy-django-app \
  --region ap-northeast-1

2. `latest` タグつきイメージの push

これらが存在しない場合は、Docker イメージを build して、ECR に push します：

# ログイン
aws ecr get-login-password --region ap-northeast-1 | docker login --username AWS --password-stdin xxx.dkr.ecr.ap-northeast-1.amazonaws.com

# ビルド
docker build -t reverse-proxy-django-nginx .

# タグづけ
docker tag reverse-proxy-django-nginx:latest xxx.dkr.ecr.ap-northeast-1.amazonaws.com/reverse-proxy-django-nginx:latest

# push
docker push xxx.dkr.ecr.ap-northeast-1.amazonaws.com/reverse-proxy-django-nginx:latest

reverse-proxy-django-app についても同様に実行します。

3. ECS タスク定義の確認

ECS の task definition で指定しているイメージ URI に誤りがないか確認します。

補註

latest タグは Docker build 時に明示的に付けないと ECR に push されません
将来的には、明確なバージョンタグ (v1.0.0 など)を利用するのが正確です

まとめ

今回のエラーは Docker イメージの push 漏れやタグ名のミスといった、基本的な操作ミスに起因していました。

ECR 上にあるべきイメージを確認し、正しいタグ名で push すること。
タスク定義の内容も見直して、リポジトリ名とタグの一致を確保すること。

今後は build → tag → push の流れをシェルスクリプト化し、再発防止につなげていきたいと思います！