buildx 멀티 아키텍처 빌드 완전 정복

지난 글에서 빌드 ARG의 고급 활용을 살펴봤다. 이번에는 하나의 이미지로 x86 서버, Apple Silicon, ARM 기기를 모두 지원하는 멀티 아키텍처 빌드를 정리한다.

왜 멀티 아키텍처인가

Apple M1/M2/M3 맥북의 보급, AWS Graviton(arm64) 인스턴스의 비용 효율성, Raspberry Pi 등 IoT 기기의 증가로 amd64 단독 이미지로는 부족해졌다. docker pull myapp:latest가 자동으로 해당 플랫폼에 맞는 레이어를 선택하려면 **manifest list(이미지 인덱스)**가 필요하다.

멀티 아키텍처 이미지 빌드 흐름

docker buildx란

docker buildx는 BuildKit 기반의 확장 빌드 CLI다. 기존 docker build와 달리 멀티 플랫폼 빌드, 빌더 인스턴스 관리, 다양한 캐시/출력 형식을 지원한다.

# 현재 빌더 목록 확인
docker buildx ls

# 기본 빌더는 단일 플랫폼만 지원
# NAME/NODE  DRIVER/ENDPOINT  STATUS  PLATFORMS
# default *  docker           running linux/amd64

멀티 플랫폼 빌더 설정

buildx 설정 및 빌드 명령

# 1. QEMU 에뮬레이터 등록 (x86 호스트에서 arm 빌드 가능)
docker run --rm --privileged \
  multiarch/qemu-user-static --reset -p yes

# 2. docker-container 드라이버로 빌더 생성
docker buildx create \
  --name multiarch \
  --driver docker-container \
  --use

# 3. 빌더 초기화 및 지원 플랫폼 확인
docker buildx inspect --bootstrap

멀티 플랫폼 빌드 및 푸시

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

--push를 반드시 지정해야 한다. 멀티 플랫폼 이미지는 로컬 Docker 데몬에 로드할 수 없고(단일 플랫폼만 가능), 레지스트리에만 manifest list로 저장된다.

# 단일 플랫폼을 로컬에 로드 (테스트용)
docker buildx build \
  --platform linux/amd64 \
  --load \
  -t myapp:test .

# manifest 내용 확인
docker buildx imagetools inspect myregistry/myapp:latest

Dockerfile에서 플랫폼 분기

BuildKit은 빌드 시 BUILDPLATFORM, TARGETPLATFORM, TARGETOS, TARGETARCH 등의 내장 ARG를 제공한다.

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.22 AS builder
ARG TARGETOS
ARG TARGETARCH
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
    go build -o /app .

FROM alpine:3.19
COPY --from=builder /app /app
CMD ["/app"]

--platform=$BUILDPLATFORM은 빌더 호스트 플랫폼(amd64)에서 Go 컴파일러를 실행하고, GOOS/GOARCH로 타겟 플랫폼 바이너리를 크로스 컴파일한다. QEMU 에뮬레이션보다 훨씬 빠르다.

GitHub Actions에서 멀티 아키텍처 빌드

name: Build and Push

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: myuser/myapp:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

플랫폼 지정 풀

# 특정 플랫폼 이미지 강제 풀
docker pull --platform linux/arm64 myapp:latest

# 현재 시스템 플랫폼 확인
docker info | grep Architecture

# 실행 중인 컨테이너 플랫폼 확인
docker inspect mycontainer | grep -i arch

베이스 이미지 플랫폼 호환성 확인

# 이미지가 지원하는 플랫폼 목록
docker buildx imagetools inspect node:20-alpine
# Image Index: ...
#   linux/amd64, linux/arm64/v8, linux/arm/v7, ...

공식 이미지 대부분은 멀티 아키텍처를 지원한다. 서드파티 이미지는 확인이 필요하다.

핵심 정리

docker buildx build --platform 으로 여러 아키텍처를 한 번에 빌드
결과물은 manifest list로 레지스트리에 저장, docker pull이 자동으로 맞는 레이어 선택
QEMU 에뮬레이션 vs 크로스 컴파일: Go/Rust 등 정적 컴파일 언어는 크로스 컴파일이 훨씬 빠름
BUILDPLATFORM, TARGETARCH 내장 ARG로 플랫폼별 빌드 분기 가능
GitHub Actions: setup-qemu-action + setup-buildx-action + build-push-action

지난 글: 빌드 ARG 고급 활용

다음 글: Dockerfile 모범 사례 총정리

읽어주셔서 감사합니다. 😊