Tech Learning Daily

コンテナは CPU までは隠してくれない

コンテナは VM と違い、ゲスト OS を持たずにホストの Linux カーネル上で直接プロセスを動かす。名前空間と cgroup で「見える範囲」と「使える量」を区切るだけなので、プロセスが実行する機械語はホストの CPU がそのまま解釈する。つまりコンテナが隠すのはファイルシステムやプロセスの見え方までで、CPU の命令セットの違いは隠さない。

ここで出てくるのが CPU アーキテクチャ、つまり CPU が理解する命令セットの種類だ。Intel / AMD のサーバーは amd64（x86_64 とも呼ぶ）、Apple Silicon の Mac や AWS Graviton は arm64（aarch64）である。Go のバイナリや Ruby の C 拡張（nokogiri など）は、コンパイル時にどちらか一方の機械語として出力される。

Linux の実行ファイル形式 ELF は、ファイル先頭のヘッダに「この機械語はどのアーキテクチャ向けか」を記録している。カーネルは execve でプログラムを起動するときにこのヘッダを確かめ、自分の CPU 向けでなければ読み込みを拒否してエラー ENOEXEC を返す。このエラーの説明文字列が「Exec format error」だ。冒頭のログは、コンテナランタイムがエントリポイントを起動しようとしてカーネルに断られたことを示している。

1 つのタグに複数のイメージが入っている

それなら node:22 や alpine のような公式イメージは、なぜ Mac でもサーバーでも同じタグで動くのか。答えは、そのタグが指しているのが 1 つのイメージではなく「目次」だからだ。イメージインデックス（Docker の用語ではマニフェストリスト）とは、アーキテクチャごとのイメージマニフェストへの参照を並べた JSON で、OCI Image Spec では各要素に platform.os・platform.architecture（必須）と platform.variant（任意）を持つと定められている。

 registry: myapp:1.0
 ┌──────────────────────────────────┐
 │ image index (manifest list)      │
 │ ├ linux/amd64    ─▶ manifest A   │
 │ └ linux/arm64/v8 ─▶ manifest B   │
 └──────────────────────────────────┘
        ▲                  ▲
   pull │                  │ pull
 ┌──────┴──────┐    ┌──────┴──────┐
 │ EC2 (amd64) │    │ Mac (arm64) │
 │ → A を取得  │    │ → B を取得  │
 └─────────────┘    └─────────────┘

 Mac で普通に build すると…
 myapp:1.0 ─▶ manifest B (arm64) のみ
 EC2 が pull → B を実行 → ENOEXEC

docker pull はまずこの目次を受け取り、ホストのアーキテクチャに合う要素を選んで中身をダウンロードする。Docker のドキュメントは「ホストのアーキテクチャに基づいて正しい variant を自動で選ぶ」と説明している。合う要素が無ければ no matching manifest for linux/amd64 in the manifest list entries のようなエラーで pull 自体が失敗する。

問題は、目次を持たない単一アーキテクチャのイメージだ。--platform を付けずに docker build すると、イメージはビルドしたマシンのプラットフォーム向けに作られる。Apple Silicon なら linux/arm64 だけになる。これを amd64 のサーバーで pull すると、選ぶ候補が 1 つしか無いので Docker は警告を出しつつそのまま取得し、起動した瞬間にカーネルに拒否される。pull は成功し、エラーは起動時にしか出ないので、デプロイの段階では気づきにくい。

なぜ Mac では amd64 イメージが動いてしまうのか

逆向き、つまり amd64 専用のイメージを Mac で動かすと、多くの場合は普通に動く。ここから「アーキテクチャの違いは Docker が吸収してくれる」と考えたくなる。しかし実際に吸収しているのは Docker Desktop が用意したエミュレーション環境で、Docker 一般の機能ではない。

その仕組みが Linux カーネルの binfmt_misc だ。これはファイル先頭のバイト列（マジックナンバー）のパターンと、それに一致したときに代わりに起動する「インタプリタ」を登録しておく機能で、登録先は /proc/sys/fs/binfmt_misc/register である。amd64 の ELF ヘッダのパターンに CPU エミュレータの QEMU を登録しておくと、カーネルは amd64 バイナリを直接実行する代わりに QEMU に渡し、QEMU が命令を 1 つずつ arm64 に翻訳しながら実行する。Docker Desktop にはこれに加えて Apple の Rosetta を使って amd64 を高速に動かす設定もある。

本番の素の Linux サーバーには、この登録が通常は入っていない。だから「Mac は arm64 も amd64 も動く」「サーバーは自分のアーキテクチャしか動かない」という非対称が生まれる。手元の動作確認が通ったことは、本番と同じアーキテクチャで動いた証拠にならない。なお QEMU によるエミュレーションは、Docker のドキュメントが「ネイティブより大幅に遅くなりうる」と注意しているとおり、コンパイルや圧縮のような計算の重い処理で特に遅い。

--platform で何が変わるか

対策は、作るイメージのプラットフォームを明示することだ。--platform にカンマ区切りで複数指定すると、BuildKit はプラットフォームごとにビルドしてイメージインデックスにまとめる。複数プラットフォームのイメージはローカルの従来型イメージストアに載せられないため、レジストリへ直接 --push するのが基本になる（Docker Desktop と Docker Engine 29.0 以降は既定の containerd イメージストアがインデックスを扱える）。

# 本番が amd64 だけなら、まずはこれで十分
docker build --platform linux/amd64 -t myapp:1.0 .

# amd64 と arm64 の両方を 1 つのタグに載せる
docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.example.com/myapp:1.0 --push .

Mac で amd64 向けをビルドすると、Dockerfile の RUN は全部エミュレーション上で走るので遅い。Go のようにクロスコンパイルできる言語なら、ビルド用ステージだけをビルドマシンのネイティブ環境で動かし、出力するバイナリの種類だけを切り替えられる。BuildKit が自動で定義するビルド引数 BUILDPLATFORM（ビルドするマシン）と TARGETOS / TARGETARCH（作りたいイメージ）を使う。

FROM --platform=$BUILDPLATFORM golang:1.23 AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY . .
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /app .

FROM gcr.io/distroless/static
COPY --from=build /app /app
ENTRYPOINT ["/app"]

FROM --platform=$BUILDPLATFORM を外すと、ビルドステージ自体が対象アーキテクチャのイメージで動くため、arm64 の Mac で amd64 をビルドするときにコンパイラまでエミュレーションで走ることになる。最終ステージには --platform を書かないので、ターゲットごとのベースイメージが使われる。Ruby のネイティブ拡張のようにクロスコンパイルしにくいものは、エミュレーションを我慢するか、CI で各アーキテクチャのネイティブマシンにビルドを任せることになる。