Dockerイメージのアーキテクチャ不一致問題

Dockerイメージのアーキテクチャ不一致問題

ビルド環境と実行環境のCPUアーキテクチャが異なる場合に発生する問題と解決方法について。

Docker #Docker#ECR#AppleSilicon

Dockerイメージのアーキテクチャ不一致問題

サムネイル

ビルド環境と実行環境のCPUアーキテクチャが異なる場合に発生する問題と解決方法について。

更新日: 8/16/2025

問題の概要

ISSUE - 課題

ECSタスクが起動直後に異常終了し、以下のエラーが発生しました。

Essential container in task exited
exec /bin/bash: exec format error

このエラーは、ARM64アーキテクチャでビルドしたDockerイメージをAMD64(x86_64)環境で実行しようとした際に発生します。

原因

Dockerイメージは特定のCPUアーキテクチャ向けにビルドされます。異なるアーキテクチャの環境で実行すると、バイナリ形式の不一致により実行できません。

一般的なアーキテクチャの組み合わせ

  • ビルド環境: ARM64(Apple Silicon、AWS Graviton など)
  • 実行環境: AMD64/x86_64(AWS Fargate、その他クラウド環境で動作するサービス)

解決方法

1. platformを指定

実行環境に合わせたアーキテクチャでbuildします。

# AMD64環境向けに
docker build --platform linux/amd64 -t image-name .

# ARM64環境向けに
docker build --platform linux/arm64 -t image-name .

2. Docker Buildxを使用

# buildxビルダーの作成
docker buildx create --name multiarch --use

# 複数アーキテクチャ対応イメージ
docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry/image-name:latest --push .

3. レガシービルダーでの対応

buildxが利用できない場合の代替方法(AppleSiliconなど)

# Docker BuildKitを無効化してビルド
DOCKER_BUILDKIT=0 docker build --platform linux/amd64 \
  -t image-name .

ベストプラクティス

Dockerfileの最適化

# マルチプラットフォーム対応の基盤イメージを使用
FROM node:20-alpine

# ビルド引数でターゲットプラットフォームを指定可能に
ARG TARGETPLATFORM
ARG BUILDPLATFORM

# プラットフォーム情報をログ出力
RUN echo "Building on $BUILDPLATFORM for $TARGETPLATFORM"

CI/CDパイプラインでの設定例

GitHub Actionsの場合

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v2

- name: Build and push
  uses: docker/build-push-action@v4
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    tags: ${{ env.REGISTRY }}/image-name:latest

開発環境では

# 開発時はネイティブアーキテクチャでビルド(高速)
docker build -t app:dev .

# 本番デプロイ前に対象のアーキテクチャでテスト
docker build --platform linux/amd64 -t app:prod .
docker run --platform linux/amd64 app:prod

トラブルシューティング

exec format error が発生する場合

  1. イメージのアーキテクチャを確認
  2. 実行環境のアーキテクチャを確認
  3. 一致しない場合は適切なプラットフォームで再ビルド

ビルドが遅い場合

クロスプラットフォームビルドはエミュレーションを使用するため、ネイティブビルドより時間がかかります。

対策

  • ビルドキャッシュの活用
  • マルチステージビルドで依存関係を分離
  • CI/CD環境でのビルド実行を検討

プラットフォーム対応表

サービス サポートアーキテクチャ
AWS Fargate AMD64(標準)、ARM64(Graviton2)
Google Cloud Run AMD64
Azure Container Instances AMD64
Kubernetes クラスタノードに依存

検索

検索条件に一致する記事が見つかりませんでした