M1·M2 맥(arm64)에서 빌드해 푸시한 이미지를 amd64 운영 서버에서 띄웠더니 exec format error가 난다면, 이미지의 CPU 아키텍처가 노드와 안 맞는 것입니다. 평소 docker build는 내 머신의 아키텍처 하나만 만듭니다. docker buildx는 amd64와 arm64를 한 번에 빌드해 같은 태그 아래 묶어주고, 레지스트리는 풀하는 쪽 아키텍처에 맞는 이미지를 자동으로 내려줍니다.
지금 이미지가 무슨 아키텍처인지 확인
# 레지스트리에 올라간 이미지의 아키텍처 목록
docker buildx imagetools inspect myapp:1.0
Platform: linux/arm64 하나만 나오면 단일 아키텍처라 amd64 서버에서 깨집니다.
1. 빌더 생성 (한 번만)
기본 빌더는 멀티플랫폼을 못 합니다. docker-container 드라이버 빌더를 만들어 씁니다.
docker buildx create --name multi --driver docker-container --use
docker buildx inspect --bootstrap
2. 멀티아키텍처 빌드 + 푸시
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t registry.example.com/myapp:1.0 \
--push .
--push가 핵심입니다. 멀티플랫폼 결과는 로컬 docker images에 못 담기므로, 레지스트리로 바로 올려 매니페스트 리스트로 묶습니다.
단계별 정리
| 단계 | 명령 | 왜 |
|---|---|---|
| 빌더 생성 | buildx create --driver docker-container | 기본 빌더는 멀티플랫폼 불가 |
| 플랫폼 지정 | --platform linux/amd64,linux/arm64 | 만들 아키텍처 명시 |
| 결과 처리 | --push (또는 --load) | 멀티는 push, 단일은 load |
| 검증 | imagetools inspect | 매니페스트에 두 아키텍처 확인 |
흔한 함정
① --load로 멀티플랫폼 — docker exporter does not currently support exporting manifest lists 에러가 납니다. --load는 단일 플랫폼만 됩니다. 멀티는 --push로 레지스트리에 올려야 합니다.
② QEMU 미설치로 크로스 빌드 실패 — 다른 아키텍처를 에뮬레이션하려면 binfmt가 필요합니다. docker run --privileged --rm tonistiigi/binfmt --install all로 한 번 등록합니다.
③ 네이티브 의존성 빌드 폭증 — 에뮬레이션 빌드는 느립니다. CI라면 amd64·arm64 러너를 각각 두고 결과를 imagetools create로 합치는 편이 빠릅니다.
확인
docker buildx imagetools inspect registry.example.com/myapp:1.0
# Platform: linux/amd64 / Platform: linux/arm64 둘 다 나오면 성공
매니페스트에 두 아키텍처가 보이면, 어떤 서버에서 풀해도 맞는 이미지가 내려갑니다.
buildx 빌더를 만들고 멀티아키텍처 이미지를 직접 푸시·검증하는 실습은 도커 트랙에서 무료로 할 수 있습니다.