Docker 이미지를 만들 때 기본적으로 사용하는 명령어는 docker build입니다.
하지만 최근에는 다양한 환경에서 Docker 이미지를 실행해야 하는 경우가 많아졌습니다.
예를 들어 하나의 애플리케이션을 다음 환경에서 모두 실행해야 할 수 있습니다.
- Intel x86 서버
- AMD 서버
- ARM 서버
- Apple Silicon Mac
- 클라우드 ARM 인스턴스
이처럼 여러 CPU 아키텍처를 지원하는 이미지를 만들기 위해 사용하는 기능이 바로 Docker Buildx입니다.
Docker Buildx는 Docker Build 기능을 확장한 도구로, 멀티 플랫폼 이미지 빌드, 고급 캐시 관리, 병렬 빌드, BuildKit 기능 등을 제공합니다.
특히 Apple M 시리즈 Mac과 ARM 기반 서버가 증가하면서 Docker Buildx의 중요성이 더욱 커지고 있습니다.
이번 글에서는 Docker Buildx의 개념부터 기본 사용법, 멀티 플랫폼 빌드, Builder 관리, 실무 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx란 무엇인가?
Docker Buildx는 Docker BuildKit 기반의 확장 빌드 도구입니다.
기존 docker build보다 다양한 기능을 제공합니다.
주요 기능:
- 멀티 플랫폼 이미지 생성
- ARM / AMD64 이미지 빌드
- 병렬 빌드 지원
- 고급 캐시 관리
- 원격 Builder 사용
- 이미지 Export 기능
Docker 공식 빌드 시스템의 핵심 도구입니다.
Docker Buildx는 언제 사용하는가?
다음과 같은 상황에서 사용합니다.
- 여러 CPU 환경 지원
- ARM 서버 배포
- Apple Silicon 개발 환경
- Kubernetes 이미지 배포
- 클라우드 멀티 아키텍처 지원
- CI/CD 자동 빌드
특히 여러 플랫폼에 서비스를 배포하는 환경에서는 필수 기능입니다.
Docker Buildx 설치 확인하기
최근 Docker 버전에서는 Buildx가 기본 포함되어 있습니다.
설치 확인:
docker buildx version출력:
github.com/docker/buildx v0.15.0정상적으로 버전이 출력되면 사용할 수 있습니다.
Docker Buildx Builder 목록 확인하기
현재 등록된 Builder를 확인합니다.
docker buildx ls출력 예:
NAME/NODE DRIVER
default docker
desktop docker-container현재 사용 가능한 Builder 목록을 확인할 수 있습니다.
Docker Buildx 기본 빌드 방법
기본적인 Buildx 사용 방법입니다.
docker buildx build -t my-app .기존 Docker Build와 비슷하지만 BuildKit 기능을 활용합니다.
이미지 생성 후 Docker 사용하기
Buildx는 기본적으로 이미지를 Docker 이미지 목록에 저장하지 않을 수 있습니다.
Docker 로컬 이미지로 저장하려면:
docker buildx build \
--load \
-t my-app .--load 옵션을 사용하면 빌드 결과가 로컬 Docker Engine에 저장됩니다.
확인:
docker images멀티 플랫폼 이미지 빌드하기
Docker Buildx의 가장 큰 장점입니다.
예:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t my-app .하나의 명령으로 두 가지 플랫폼 이미지를 생성합니다.
지원 플랫폼:
linux/amd64
linux/arm64
linux/arm/v7Docker Hub에 멀티 플랫폼 이미지 Push하기
멀티 플랫폼 이미지는 Registry에 저장해야 합니다.
예:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t username/my-app:latest \
--push .빌드 후 Docker Hub에 자동 업로드됩니다.
Buildx와 BuildKit 관계
Docker Buildx는 BuildKit 기능을 사용하는 확장 도구입니다.
구조:
Dockerfile
↓
Docker Buildx
↓
BuildKit
↓
Docker ImageBuildKit은 빠른 빌드, 병렬 처리, 효율적인 Cache 관리를 제공합니다.
Docker Buildx 실무 활용 예제
Docker Buildx는 하나의 Dockerfile을 사용하여 여러 CPU 아키텍처용 이미지를 생성할 수 있어 클라우드 환경과 다양한 서버 환경에서 매우 유용합니다.
특히 ARM 서버와 AMD64 서버를 동시에 운영하는 환경에서는 Buildx 활용이 필수적입니다.
Buildx Builder 생성 후 사용하기
먼저 Builder를 생성합니다.
docker buildx create \
--name multi-builder \
--use생성된 Builder를 확인합니다.
docker buildx ls출력:
NAME DRIVER
multi-builder * docker-container현재 Builder가 활성화된 것을 확인할 수 있습니다.
ARM과 AMD64 이미지 동시에 빌드하기
멀티 플랫폼 이미지를 생성합니다.
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t my-app:latest .두 가지 환경에서 실행 가능한 이미지를 만들 수 있습니다.
Docker Hub에 Push하기
멀티 플랫폼 이미지는 Registry 저장이 필요합니다.
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t username/my-app:latest \
--push .Push 완료 후:
- Intel 서버
- AMD 서버
- ARM 서버
모두 동일한 이미지 이름으로 사용할 수 있습니다.
로컬 Docker에 이미지 저장하기
Buildx 결과를 로컬 Docker Engine으로 가져옵니다.
docker buildx build \
--load \
-t my-app:test .확인:
docker images로컬 이미지 목록에서 확인할 수 있습니다.
빌드 결과 파일로 저장하기
이미지를 파일 형태로 저장할 수도 있습니다.
docker buildx build \
--output type=docker \
-t my-app .Docker 이미지 형식으로 출력됩니다.
Build Cache 활용하기
Buildx에서는 고급 Cache 기능을 사용할 수 있습니다.
Cache 저장:
docker buildx build \
--cache-to type=local,dest=/tmp/cache .Cache 사용:
docker buildx build \
--cache-from type=local,src=/tmp/cache .CI/CD 환경에서 빌드 시간을 줄이는 데 효과적입니다.
Linux 서버 문제 해결
서비스를 ARM 기반 클라우드 서버와 기존 AMD64 서버에 동시에 배포해야 하는 상황이 발생했습니다.
기존 방식으로 이미지를 만들 경우:
docker build -t web-app .AMD64 환경에서는 정상 실행되었지만 ARM 서버에서는 오류가 발생했습니다.
원인은 이미지가 특정 CPU 아키텍처만 지원했기 때문입니다.
관리자는 Buildx를 사용하여 멀티 플랫폼 이미지를 생성했습니다.
Builder 생성:
docker buildx create \
--name production-builder \
--use멀티 플랫폼 빌드:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/web-app:v1 \
--push .이후 ARM 서버와 AMD64 서버 모두 동일한 이미지를 사용할 수 있게 되었습니다.
Docker Buildx를 활용하면 서버 환경이 달라도 하나의 이미지 관리 체계를 구축할 수 있습니다.
Docker Buildx 사용 시 주의사항
Docker Buildx를 사용할 때는 다음 사항을 확인해야 합니다.
첫 번째는 멀티 플랫폼 이미지는 일반적으로 Registry Push가 필요하다는 점입니다.
여러 플랫폼 이미지를 하나의 로컬 이미지로 저장하는 것은 제한적입니다.
두 번째는 ARM과 AMD64 환경에서 사용하는 Base Image가 해당 플랫폼을 지원해야 합니다.
세 번째는 Builder 설정에 따라 빌드 속도와 기능이 달라질 수 있습니다.
네 번째는 CI/CD 환경에서는 Cache 설정을 함께 구성하면 빌드 시간을 크게 줄일 수 있습니다.
Best Practice
Docker Buildx를 사용할 때는 다음 방법을 추천합니다.
- 프로젝트별 Builder를 관리합니다.
- 멀티 플랫폼 빌드는 명확한 Tag를 사용합니다.
- Registry Push 방식을 활용합니다.
- Build Cache를 적극 활용합니다.
- CI/CD 환경과 연동합니다.
- 빌드 후 실제 플랫폼에서 테스트합니다.
이러한 방법을 적용하면 다양한 서버 환경에서도 안정적인 Docker 이미지 배포가 가능합니다.
자주 묻는 질문
Docker Buildx와 Docker Build의 차이는 무엇인가요?
Docker Build는 기본 이미지 빌드 기능이고, Buildx는 BuildKit 기반의 확장 기능으로 멀티 플랫폼 빌드와 고급 Cache 기능을 제공합니다.
ARM과 AMD64 이미지를 동시에 만들 수 있나요?
가능합니다.
--platform 옵션을 사용하면 여러 아키텍처 이미지를 생성할 수 있습니다.
Buildx 이미지는 바로 실행할 수 있나요?
옵션에 따라 다릅니다.
로컬에서 사용하려면 --load, Registry 저장은 --push를 사용합니다.
Buildx는 별도 설치가 필요한가요?
최근 Docker 버전에서는 기본 포함되어 있습니다.
마무리
Docker Buildx는 기존 Docker Build 기능을 확장하여 멀티 플랫폼 이미지 생성과 고급 빌드 관리를 가능하게 하는 강력한 도구입니다.
특히 ARM 서버와 AMD64 서버를 함께 운영하는 환경에서는 하나의 Dockerfile로 다양한 플랫폼 이미지를 생성할 수 있어 배포 효율을 크게 높일 수 있습니다.
또한 Build Cache, Builder 관리, CI/CD 연동 기능을 활용하면 더욱 빠르고 안정적인 Docker 이미지 빌드 환경을 구축할 수 있습니다.