はじめに

AWS ECS（または Fargate）で Docker イメージを使ってコンテナをデプロイしようとしたところ、次のようなエラーが発生しました。

CannotPullContainerError: pull image manifest has been retried 5 time(s): 
image manifest does not contain descriptor matching platform 'linux/amd64'

これは、コンテナイメージが linux/amd64 アーキテクチャに対応していない場合に発生する典型的なエラーです。本記事では、原因と解決法を具体的に解説します。

エラーの意味

このエラーは、ECS が Docker イメージを pull（取得）しようとしたときに：

ターゲットプラットフォーム：linux/amd64
しかし、リモートのイメージにはそのプラットフォームに対応する descriptor（イメージ情報）が存在しなかった
という状況を表します。
つまり、イメージはあるけど、ECS が必要としているアーキテクチャ用ではない ということ。

原因

✅ よくある原因：ビルドしたイメージが linux/amd64 に対応していない
Docker イメージを docker build でビルドしただけでは、そのマシンのアーキテクチャ（たとえば M1 Mac なら arm64）に最適化されたイメージが作られます。
その結果：

ECS（x86_64 基盤）からは非対応のイメージに見えてしまう
CannotPullContainerError が発生する

解決方法

✅ 解決策①：buildx を使って linux/amd64 向けにビルド＆push する

docker buildx build \
  --platform linux/amd64 \
  -t 127929167946.dkr.ecr.ap-northeast-1.amazonaws.com/ctn-cicd-hdon-repo:latest \
  --push \
  .
* --platform linux/amd64：ECS 用に x86 アーキテクチャでビルド
* --push：ECR に直接 push（これがないとマニフェストが付かない）

🔍 プラットフォーム確認コマンド

まとめ

原因

イメージが linux/amd64 に対応していない

対応

docker buildx build --platform linux/amd64 ... --push を使う
イメージが arm64 のみ ECS タスク定義で ARM64 を指定する
docker build のみでイメージを作っていた buildx を使ってプラットフォーム明示する

さいごに

このエラーはコンテナ開発初期にかなり頻繁に遭遇する落とし穴です。Docker のビルドプラットフォームと ECS の実行環境が一致しているかどうか、これを常に意識することで、トラブルを未然に防げます。