Docker 이미지를 생성할 때 가장 기본적으로 사용하는 명령어는 docker build입니다.
하지만 최신 Docker 환경에서는 BuildKit 기반의 고급 빌드 기능을 제공하는 Docker Buildx Build를 많이 사용합니다.
Docker Buildx Build는 기존 Docker Build 기능을 확장한 명령어로 다음과 같은 고급 기능을 제공합니다.
- 멀티 플랫폼 이미지 빌드
- 병렬 빌드
- 고급 Cache 관리
- 다양한 출력(Output) 방식
- Registry 직접 Push
- BuildKit 기반 최적화
특히 ARM과 AMD64 환경을 동시에 지원해야 하는 서비스에서는 필수적으로 사용됩니다.
이번 글에서는 Docker Buildx Build의 개념부터 기본 사용법, 주요 옵션, 멀티 플랫폼 빌드, CI/CD 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx Build란 무엇인가?
Docker Buildx Build는 Docker Buildx를 이용하여 Docker 이미지를 생성하는 명령어입니다.
기존:
docker build .확장 방식:
docker buildx build .BuildKit 엔진을 사용하여 더욱 다양한 빌드 기능을 제공합니다.
Docker Buildx Build의 주요 특징
Docker Buildx Build는 다음 기능을 지원합니다.
멀티 플랫폼 빌드
하나의 명령으로 여러 CPU 환경용 이미지를 생성할 수 있습니다.
예:
--platform linux/amd64,linux/arm64Cache 활용
기존 빌드 결과를 재사용하여 속도를 향상시킵니다.
병렬 빌드
여러 단계의 빌드를 효율적으로 처리합니다.
Registry Push
빌드 후 바로 Docker Hub 또는 Private Registry에 업로드할 수 있습니다.
Docker Buildx Build 기본 사용법
기본 형식:
docker buildx build [옵션] 경로예:
docker buildx build .현재 디렉터리의 Dockerfile을 사용하여 이미지를 빌드합니다.
이미지 이름 지정하기
-t 옵션으로 이미지 이름을 지정합니다.
docker buildx build \
-t my-app:latest .생성 이미지:
my-app:latestDockerfile 지정하기
다른 Dockerfile을 사용할 수 있습니다.
docker buildx build \
-f Dockerfile.prod \
-t app:v1 .운영용 Dockerfile과 개발용 Dockerfile을 분리할 때 사용합니다.
Build Context 지정하기
빌드 대상 경로를 지정합니다.
예:
docker buildx build \
-t frontend:v1 \
./frontend특정 폴더 기준으로 이미지를 생성합니다.
Docker Buildx Build 멀티 플랫폼 빌드
가장 대표적인 Buildx 기능입니다.
예:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:v1 \
--push .생성:
linux/amd64 이미지
linux/arm64 이미지하나의 Tag로 여러 환경을 지원할 수 있습니다.
Docker Buildx Build Push 옵션
Registry에 바로 업로드하려면:
docker buildx build \
-t company/app:v1 \
--push .사용합니다.
일반 Docker Build와 달리 Buildx는 기본적으로 로컬 이미지 저장을 하지 않을 수 있습니다.
Docker Buildx Build Load 옵션
로컬 Docker 이미지로 저장하려면:
docker buildx build \
-t app:v1 \
--load .사용합니다.
이후:
docker images에서 확인할 수 있습니다.
Docker Buildx Build Cache 설정
Cache를 사용하면 반복 빌드 속도를 높일 수 있습니다.
예:
docker buildx build \
--cache-from type=registry,ref=app:cache \
--cache-to type=registry,ref=app:cache \
-t app:v1 \
--push .CI/CD 환경에서 많이 사용합니다.
Docker Buildx Build Progress 설정
빌드 출력 방식을 변경할 수 있습니다.
기본:
docker buildx build .상세 출력:
docker buildx build \
--progress=plain .문제 분석 시 유용합니다.
Docker Buildx Build 실무 활용 예제
일반 이미지 빌드
docker buildx build \
-t nginx-custom:v1 .Docker 이미지를 생성합니다.
멀티 플랫폼 배포 이미지 생성
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/web:latest \
--push .서버 환경에 맞는 이미지를 자동 선택할 수 있습니다.
CI/CD 자동 빌드
GitHub Actions 같은 환경:
docker buildx build \
--platform linux/amd64 \
-t company/app:${VERSION} \
--push .배포 파이프라인에 사용할 수 있습니다.
Linux 서버 문제 해결
운영 서버에서 ARM 환경 배포를 진행했지만 이미지 실행 오류가 발생했습니다.
오류:
no matching manifest for linux/arm64이미지를 확인했습니다.
docker buildx imagetools inspect company/app:latest결과:
linux/amd64 onlyAMD64 이미지만 생성된 상태였습니다.
멀티 플랫폼 빌드를 적용했습니다.
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:latest \
--push .확인:
docker buildx imagetools inspect company/app:latest결과:
linux/amd64
linux/arm64ARM 서버에서도 정상적으로 실행되었습니다.
Docker Buildx Build 사용 시 주의사항
첫 번째는 Buildx Builder 상태를 먼저 확인하는 것이 좋습니다.
docker buildx ls두 번째는 멀티 플랫폼 빌드 시 반드시 --push 또는 --load 옵션을 고려해야 합니다.
세 번째는 Registry Push 전 이미지 Tag 규칙을 정하는 것이 중요합니다.
네 번째는 Cache 설정을 잘못하면 오래된 이미지가 사용될 수 있습니다.
Best Practice
Docker Buildx Build를 사용할 때는 다음 방법을 추천합니다.
- 멀티 플랫폼은 Buildx를 사용합니다.
- 운영 이미지는 버전 Tag를 사용합니다.
- CI/CD에서는 Cache를 활용합니다.
- 빌드 전 Builder 상태를 확인합니다.
- Push 전 이미지 검증을 진행합니다.
- Dockerfile 최적화를 함께 진행합니다.
자주 묻는 질문
Docker Buildx Build와 Docker Build 차이는 무엇인가요?
Buildx Build는 BuildKit 기반이며 멀티 플랫폼과 고급 Cache 기능을 지원합니다.
Buildx Build 결과가 docker images에 안 보이는 이유는 무엇인가요?
기본 출력 방식이 Registry 또는 Cache 기반일 수 있기 때문입니다.
로컬 저장은 --load 옵션을 사용합니다.
멀티 플랫폼 이미지는 어떻게 만드나요?
--platform 옵션을 사용합니다.
예:
--platform linux/amd64,linux/arm64CI/CD에서 사용할 수 있나요?
가능합니다.
자동 이미지 빌드와 배포 환경에서 많이 활용됩니다.
마무리
Docker Buildx Build는 현대적인 Docker 이미지 빌드를 위한 핵심 명령어입니다.
기존 Docker Build보다 강력한 기능을 제공하며 멀티 플랫폼 이미지 생성, Cache 관리, Registry Push, CI/CD 자동화 등 다양한 환경에서 활용할 수 있습니다.
특히 클라우드 서버와 Kubernetes 환경에서는 Docker Buildx Build를 활용한 이미지 관리가 안정적인 배포 환경을 만드는 중요한 요소입니다.