핵심 정리

# buildx 빌더 생성 (처음 한 번)
docker buildx create --name mybuilder --use

# amd64와 arm64를 동시에 빌드해 레지스트리에 푸시
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myorg/myapp:1.0.0 \
  --push .

기본 흐름

어떤 멀티 플랫폼 빌드 기준을 먼저 떠올리면 되나

buildx가 기본 docker build와 다른 점 — BuildKit 기반으로 멀티 플랫폼과 고급 캐시를 지원한다

docker build는 현재 머신 아키텍처용 이미지 하나만 만들 수 있습니다. docker buildx는 BuildKit을 기반으로 동작하며, --platform 플래그로 여러 아키텍처를 한 번에 빌드하고 레지스트리에 manifest list(멀티 플랫폼 이미지 묶음)로 푸시할 수 있습니다. Apple Silicon 개발 환경과 x86 서버가 혼재하는 팀에서 필수 도구가 됐습니다.

# 현재 사용 가능한 빌더 목록 확인
docker buildx ls

# QEMU 에뮬레이터 등록 (교차 빌드에 필요)
docker run --privileged --rm tonistiigi/binfmt --install all

--platform 플래그로 linux/amd64, linux/arm64 동시 빌드

--platform 플래그에 콤마로 여러 아키텍처를 지정하면 BuildKit이 각 플랫폼용 이미지를 별도로 빌드합니다. 빌드 결과는 단일 태그 아래 여러 플랫폼 매니페스트를 담은 OCI image index로 레지스트리에 저장됩니다. 사용자가 docker pull하면 자신의 머신에 맞는 이미지를 자동으로 받습니다.

docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t myorg/myapp:latest \
  --push .

# 특정 플랫폼으로 로컬 테스트
docker run --platform linux/arm64 myorg/myapp:latest

QEMU 에뮬레이션 방식과 성능 비용 — 크로스 컴파일이 가능하지만 빌드가 느려진다

자신과 다른 아키텍처를 빌드할 때 Docker는 QEMU를 통해 CPU 명령어를 에뮬레이션합니다. 예를 들어 x86_64 머신에서 arm64 이미지를 빌드하면 QEMU가 arm64 명령어를 에뮬레이션해 실행하므로, 네이티브 빌드보다 훨씬 느릴 수 있습니다. CI에서 빠른 빌드가 필요하다면 네이티브 arm64 러너를 별도로 운영하는 방법도 고려해야 합니다.

# CI에서 캐시를 활용한 멀티 플랫폼 빌드
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --cache-from type=registry,ref=myorg/myapp:cache \
  --cache-to type=registry,ref=myorg/myapp:cache,mode=max \
  -t myorg/myapp:latest \
  --push .

--push와 --load는 결과를 두는 위치가 다르다

--push는 빌드 결과를 레지스트리에 올리고, --load는 결과를 현재 머신의 로컬 Docker image store로 가져옵니다. 멀티 플랫폼 이미지는 보통 manifest list 형태라 로컬로 한 번에 적재할 수 없어 --push가 기본 선택이 되고, 로컬 테스트용 단일 플랫폼 빌드는 --load가 더 편합니다.

# 멀티 플랫폼 결과를 레지스트리로 푸시
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myorg/myapp:latest \
  --push .

# 로컬 단일 플랫폼 테스트
docker buildx build \
  --platform linux/arm64 \
  -t myapp:test \
  --load .

체크포인트

주의할 점

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:test \
  --load .

멀티 플랫폼 빌드에서 --load를 기대하면 보통 한 플랫폼만 로컬에 적재되거나 오류가 납니다. 여러 플랫폼을 함께 만들 때는 --push를 기본으로 보고, 로컬 검증은 플랫폼을 하나로 줄여 따로 테스트하는 편이 안전합니다.