# 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 buildx는 선택 가능한 BuildKit builder와 export를 제공하며, --platform으로 여러 아키텍처를 빌드해 registry에 OCI image index(멀티 플랫폼 이미지 묶음)로 푸시할 수 있습니다. 단일 플랫폼 docker build와 buildx의 차이를 "명령 이름"보다 builder driver·플랫폼·결과 export로 구분합니다.

# 현재 사용 가능한 빌더 목록 확인
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 에뮬레이션은 한 가지 전략일 뿐이다

자신과 다른 아키텍처의 RUN을 실행해야 할 때 QEMU 에뮬레이션을 쓸 수 있지만, 모든 멀티 플랫폼 빌드가 QEMU를 요구하는 것은 아닙니다. cross-compilation과 플랫폼별 native builder도 선택지입니다. 에뮬레이션은 느릴 수 있으므로 CI에서는 대상 아키텍처 native runner나 multi-node builder를 검토합니다.

# 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 .

플랫폼별 실행 검증