Docker for Mac（M1）でのプラットフォーム不一致エラーと解決策

問題

Apple Silicon（M1/M2）搭載のMacでDockerを実行する際、次のような警告メッセージが表示されることがあります：

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

このエラーは、AMD64（x86_64）アーキテクチャ用にビルドされたDockerイメージを、ARM64アーキテクチャのMac上で実行しようとした際に発生します。

原因

Apple Silicon MacはARM64アーキテクチャを採用しているのに対し、多くのDockerイメージは従来のAMD64アーキテクチャ用にビルドされています。このアーキテクチャの不一致により、互換性の問題が生じます。

解決策

1. プラットフォームの明示的指定（推奨）

Dockerコマンド実行時にプラットフォームを明示的に指定します：

docker run --platform linux/amd64 -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:12.0.4

2. 環境変数によるデフォルト設定

すべてのDockerコマンドでAMD64プラットフォームを使用するように環境変数を設定します：

export DOCKER_DEFAULT_PLATFORM=linux/amd64

その後、通常通りDockerコマンドを実行：

docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:12.0.4

3. Docker Composeでの設定

docker-compose.ymlファイル内でプラットフォームを指定します：

services:
  keycloak:
    platform: linux/amd64
    image: quay.io/keycloak/keycloak:12.0.4
    ports:
      - "8080:8080"
    environment:
      - KEYCLOAK_USER=admin
      - KEYCLOAK_PASSWORD=admin

4. Docker DesktopのRosetta設定を有効化

INFO

この方法はDocker Desktop for Macで利用可能です

1. Docker Desktopを開く
2. 設定 > Features in development に移動
3. "Use Rosetta for x86/amd64 emulation on Apple Silicon" を有効化

RosettaはApple Silicon上でx86命令をARM命令に変換するバイナリ変換技術で、AMD64イメージの実行を可能にします。

5. カスタム関数の定義（シェル設定）

~/.zshrc または ~/.bashrc に次の関数を追加することで、自動的にプラットフォームを指定できます：

# M1 MacでのDockerプラットフォーム自動設定
docker() {
  if [[ `uname -m` == "arm64" ]] && [[ "$1" == "run" || "$1" == "build" ]]; then
    /usr/local/bin/docker "$1" --platform linux/amd64 "${@:2}"
  else
    /usr/local/bin/docker "$@"
  fi
}

設定後、ターミナルを再起動するか、source ~/.zshrc を実行して変更を反映させます。

6. Buildxを使用したマルチプラットフォームビルド

Docker Buildxを使用して、明示的にAMD64用のイメージをビルドします：

docker buildx build --platform=linux/amd64 -t myimage:latest .

詳細説明

根本的な原因の理解

重要

この問題は、M1 Mac上でビルドしたイメージを他のプラットフォームで実行しようとした場合にも発生する可能性があります

ベースイメージのビルド時にプラットフォームを指定しなかった場合、後続のビルドでプラットフォーム不一致の問題が発生することがあります。常にビルド時にターゲットプラットフォームを明示的に指定することが推奨されます。

永続的な解決策

長期的には、マルチアーキテクチャイメージの使用を検討してください。多くの公式Dockerイメージは現在、AMD64とARM64の両方のアーキテクチャをサポートするマルチプラットフォームイメージを提供しています。

トラブルシューティング

問題が解決しない場合は、以下のコマンドでDockerのキャッシュをクリーンアップしてみてください：

docker system prune --all

その後、再度イメージのビルドと実行を試みてください。

まとめ

Apple Silicon MacでのDocker使用時のプラットフォーム不一致問題は、以下のいずれかの方法で解決できます：

1. --platform linux/amd64 フラグの使用
2. 環境変数 DOCKER_DEFAULT_PLATFORM の設定
3. Docker DesktopのRosetta機能の有効化
4. マルチプラットフォームイメージの使用

これらの解決策により、M1/M2 Macでも従来のAMD64用Dockerイメージを問題なく実行できるようになります。