Docker Buildx Build -platform 사용법 완벽 가이드! 멀티 플랫폼 이미지 관리하기

최근 Docker 환경에서는 하나의 서버 환경만 고려하는 것이 아니라 다양한 CPU 아키텍처를 지원해야 하는 경우가 많아졌습니다.

예:

Intel 서버
AMD 서버
Apple Silicon Mac
AWS Graviton ARM 서버
Raspberry Pi 환경
Kubernetes 멀티 아키텍처 클러스터

이처럼 서로 다른 환경에서 같은 Docker 이미지를 실행하려면 플랫폼에 맞는 이미지가 필요합니다.

Docker Buildx Build에서는 --platform 옵션을 사용하여 원하는 운영체제와 CPU 아키텍처용 이미지를 생성할 수 있습니다.

예:

docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:v1 \
--push .

하나의 Docker 이미지 Tag로 여러 플랫폼 환경을 지원할 수 있습니다.

이번 글에서는 Docker Buildx Build –platform의 개념부터 플랫폼 종류, 멀티 플랫폼 빌드 방법, ARM64 지원, 실무 활용 방법까지 자세히 알아보겠습니다.

Table of Contents

Docker Buildx Build –platform이란 무엇인가?

--platform은 Docker 이미지를 빌드할 대상 플랫폼을 지정하는 옵션입니다.

기본 형식:

docker buildx build \
--platform 플랫폼명 .

예:

docker buildx build \
--platform linux/amd64 .

AMD64 환경용 Docker 이미지를 생성합니다.

Docker Platform이란 무엇인가?

Docker Platform은 이미지가 실행될 운영체제와 CPU 구조를 의미합니다.

구성:

OS / Architecture

대표적인 플랫폼:

linux/amd64

linux/arm64

linux/arm/v7

Docker Buildx Build –platform이 필요한 이유

일반적인 Docker Build:

docker build .

현재 컴퓨터 환경에 맞춰 이미지가 생성됩니다.

예:

Apple Silicon Mac:

linux/arm64

Intel 서버:

linux/amd64

서로 다른 환경에서는 실행 문제가 발생할 수 있습니다.

--platform을 사용하면 여러 환경을 지원할 수 있습니다.

Docker Buildx Build –platform 기본 사용법

AMD64 이미지 생성

docker buildx build \
--platform linux/amd64 \
-t app:amd64 .

Intel·AMD 서버용 이미지를 생성합니다.

ARM64 이미지 생성

docker buildx build \
--platform linux/arm64 \
-t app:arm64 .

ARM 기반 환경용 이미지를 생성합니다.

Docker Buildx Build 멀티 플랫폼 빌드

가장 많이 사용하는 방식입니다.

docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:latest \
--push .

생성 구조:

company/app:latest

├── linux/amd64

└── linux/arm64

Docker는 실행 환경에 맞는 이미지를 자동으로 선택합니다.

멀티 플랫폼 이미지 확인하기

빌드 후:

docker buildx imagetools inspect company/app:latest

결과:

Platforms:

linux/amd64

linux/arm64

지원 플랫폼을 확인할 수 있습니다.

Docker Buildx Build –platform 주요 플랫폼 종류

linux/amd64

가장 일반적인 서버 환경입니다.

사용:

Intel CPU 서버
AMD CPU 서버
대부분의 클라우드 VM

linux/arm64

ARM 기반 환경입니다.

사용:

Apple Silicon Mac
AWS Graviton
ARM 서버

linux/arm/v7

32비트 ARM 환경입니다.

사용:

일부 Raspberry Pi
임베디드 환경

Docker Buildx Build –platform과 Registry 관계

멀티 플랫폼 이미지는 일반적으로 Registry Push 방식을 사용합니다.

예:

docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:v1 \
--push .

이유:

하나의 로컬 Docker Engine에 여러 플랫폼 이미지를 동시에 저장하기 어렵기 때문입니다.

Docker Buildx Build –platform 실무 활용 예제

AWS ARM 서버 지원

기존:

docker buildx build \
-t backend:v1 .

결과:

linux/amd64

ARM 서버에서는 실행 문제가 발생할 수 있습니다.

해결:

docker buildx build \
--platform linux/amd64,linux/arm64 \
-t backend:v1 \
--push .

AMD와 ARM 환경 모두 지원합니다.

CI/CD 멀티 플랫폼 빌드

자동 배포 환경:

docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:${VERSION} \
--push .

여러 서버 환경에 대응하는 이미지를 자동 생성합니다.

Linux 서버 문제 해결

ARM 서버에서 Docker 실행 오류가 발생했습니다.

오류:

no matching manifest for linux/arm64

이미지 확인:

docker buildx imagetools inspect company/app:latest

결과:

Platforms:

linux/amd64

AMD64 이미지만 존재했습니다.

해결:

docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:latest \
--push .

확인:

docker buildx imagetools inspect company/app:latest

결과:

Platforms:

linux/amd64

linux/arm64

ARM 서버에서도 정상 실행되었습니다.

Docker Buildx Build –platform 사용 시 주의사항

첫 번째는 멀티 플랫폼 빌드에는 적절한 Builder 설정이 필요합니다.

두 번째는 플랫폼별 테스트가 필요합니다.

세 번째는 멀티 플랫폼 이미지는 일반적으로 --push를 사용합니다.

네 번째는 모든 플랫폼을 추가하기보다 필요한 환경만 지정하는 것이 좋습니다.

Best Practice

Docker Buildx Build –platform 활용 방법:

필요한 플랫폼만 지정
ARM과 AMD 환경 테스트
멀티 플랫폼은 Registry 관리
CI/CD 자동화 활용
imagetools inspect로 검증
버전 Tag 사용

자주 묻는 질문

Docker Buildx Build –platform은 무엇인가요?

Docker 이미지가 실행될 CPU와 운영체제 플랫폼을 지정하는 옵션입니다.

여러 플랫폼 이미지를 만들 수 있나요?

가능합니다.

예:

--platform linux/amd64,linux/arm64

왜 멀티 플랫폼 이미지가 필요한가요?

서버와 개발 환경의 CPU 구조가 다양해졌기 때문입니다.

ARM과 AMD64 이미지를 하나의 Tag로 관리할 수 있나요?