Docker 이미지는 기본적으로 현재 실행 중인 CPU 환경에 맞춰 빌드됩니다.
예를 들어:
- Intel·AMD 서버 → linux/amd64
- ARM 서버 → linux/arm64
하지만 최근에는 하나의 애플리케이션을 여러 환경에서 실행해야 하는 경우가 많아졌습니다.
예:
- AWS Graviton ARM 서버
- Apple Silicon Mac
- 일반 x86 서버
- Kubernetes 멀티 아키텍처 환경
이때 필요한 기능이 바로 Docker Buildx Build –platform 옵션입니다.
--platform 옵션을 사용하면 하나의 Dockerfile을 기반으로 여러 CPU 아키텍처용 이미지를 생성할 수 있습니다.
예:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t my-app:v1 \
--push .하나의 이미지 Tag로 여러 플랫폼을 지원할 수 있습니다.
이번 글에서는 Docker Buildx Build –platform의 개념부터 기본 사용법, 멀티 플랫폼 이미지 생성, ARM·AMD64 지원, 실무 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –platform이란 무엇인가?
--platform은 Docker 이미지를 생성할 대상 플랫폼을 지정하는 옵션입니다.
기본 형식:
docker buildx build \
--platform 플랫폼명 .예:
docker buildx build \
--platform linux/amd64 .AMD64 환경용 이미지를 생성합니다.
Docker Platform이란 무엇인가?
Platform은 Docker 이미지가 실행되는 운영체제와 CPU 구조를 의미합니다.
구성:
OS / Architecture예:
linux/amd64
linux/arm64
linux/arm/v7각 환경에 맞는 이미지가 필요합니다.
Docker Buildx Build –platform을 사용하는 이유
일반적인 Docker Build:
docker build .현재 컴퓨터 환경 기준으로 생성됩니다.
예:
Apple Silicon Mac:
linux/arm64서버:
linux/amd64다른 환경에서는 실행 문제가 발생할 수 있습니다.
--platform을 사용하면 여러 환경을 지원할 수 있습니다.
Docker Buildx Build –platform 기본 사용법
단일 플랫폼 빌드
AMD64 이미지:
docker buildx build \
--platform linux/amd64 \
-t app:v1 .ARM64 이미지:
docker buildx build \
--platform linux/arm64 \
-t app:v1 .멀티 플랫폼 빌드하기
가장 많이 사용하는 방식입니다.
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:v1 \
--push .생성:
company/app:v1
├── linux/amd64
└── linux/arm64Docker는 실행 환경에 맞는 이미지를 자동 선택합니다.
지원 플랫폼 확인하기
빌드 후 확인:
docker buildx imagetools inspect company/app:v1결과:
Platforms:
linux/amd64
linux/arm64정상적으로 멀티 플랫폼 이미지가 생성된 것을 확인할 수 있습니다.
자주 사용하는 Platform 종류
linux/amd64
일반적인 Intel·AMD 서버 환경입니다.
사용:
- AWS EC2 일반 인스턴스
- 대부분의 클라우드 서버
- 기존 Linux 서버
linux/arm64
ARM 기반 환경입니다.
사용:
- Apple Silicon
- AWS Graviton
- ARM 서버
linux/arm/v7
32비트 ARM 환경입니다.
사용:
- Raspberry Pi 일부 모델
- 임베디드 장비
Docker Buildx Build –platform과 Push 관계
멀티 플랫폼 빌드는 일반적으로 Registry 저장이 필요합니다.
예:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t app:v1 \
--push .이유:
여러 플랫폼 이미지는 하나의 로컬 이미지로 저장하기 어렵기 때문입니다.
Registry에서는 Manifest를 통해 관리합니다.
Docker Buildx Build –platform과 Load 차이
–push
Registry 저장:
--push멀티 플랫폼 권장 방식입니다.
–load
로컬 저장:
--load단일 플랫폼 테스트에 적합합니다.
멀티 플랫폼 이미지에서는 일반적으로 사용할 수 없습니다.
Docker Buildx Build –platform 실무 활용 예제
ARM 서버 지원 이미지 만들기
기존:
docker buildx build \
-t server:v1 .결과:
linux/amd64ARM 서버에서 실행 실패 가능성이 있습니다.
해결:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t server:v1 \
--push .이제 두 환경 모두 지원합니다.
CI/CD 멀티 플랫폼 빌드
GitHub Actions 같은 자동화 환경:
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/amd64AMD64 이미지만 존재했습니다.
멀티 플랫폼으로 다시 빌드:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:latest \
--push .확인:
docker buildx imagetools inspect company/app:latest결과:
Platforms:
linux/amd64
linux/arm64ARM 서버에서도 정상 실행됩니다.
Docker Buildx Build –platform 사용 시 주의사항
첫 번째는 멀티 플랫폼 빌드에는 적절한 Builder가 필요합니다.
확인:
docker buildx ls두 번째는 QEMU 에뮬레이션 환경이 필요할 수 있습니다.
세 번째는 멀티 플랫폼 이미지는 일반적으로 --push를 사용합니다.
네 번째는 플랫폼별 테스트를 진행하는 것이 좋습니다.
Best Practice
Docker Buildx Build –platform 활용 방법:
- 운영 환경 플랫폼을 먼저 확인합니다.
- 필요한 플랫폼만 지정합니다.
- 멀티 플랫폼은 Registry Push를 사용합니다.
- 빌드 후 Inspect로 확인합니다.
- CI/CD에서 자동화합니다.
- ARM·AMD64 환경을 모두 테스트합니다.
자주 묻는 질문
–platform 옵션은 무엇인가요?
Docker 이미지가 실행될 플랫폼을 지정하는 옵션입니다.
여러 플랫폼 이미지를 만들 수 있나요?
가능합니다.
예:
--platform linux/amd64,linux/arm64왜 멀티 플랫폼 이미지가 필요한가요?
서버 CPU 환경이 다양해졌기 때문입니다.
멀티 플랫폼 빌드는 어디에 저장되나요?
일반적으로 Docker Hub 같은 Registry에 Push하여 관리합니다.
마무리
Docker Buildx Build –platform 옵션은 현대 Docker 환경에서 가장 중요한 기능 중 하나입니다.
하나의 Dockerfile로 AMD64, ARM64 등 다양한 환경을 지원하는 이미지를 생성할 수 있으며, 클라우드 서버와 Kubernetes 환경에서 필수적으로 활용됩니다.
특히 여러 CPU 아키텍처를 지원하는 서비스를 운영한다면 --platform 옵션과 --push, imagetools inspect를 함께 사용하여 안정적인 멀티 플랫폼 이미지 관리 환경을 구축할 수 있습니다.