Docker Buildx Build는 단순히 Docker 이미지를 생성하는 기능뿐만 아니라 다양한 옵션을 활용하여 빌드 환경을 세밀하게 제어할 수 있습니다.
기본적인 이미지 생성은 다음 명령으로 가능합니다.
docker buildx build .하지만 실제 운영 환경에서는 다음과 같은 요구사항이 발생합니다.
- 특정 플랫폼용 이미지 생성
- 이미지 Tag 관리
- Registry Push
- Cache 활용
- Dockerfile 변경
- 빌드 출력 방식 변경
- 빌드 정보 확인
이러한 작업은 Docker Buildx Build 옵션을 통해 관리할 수 있습니다.
이번 글에서는 Docker Buildx Build에서 자주 사용하는 주요 옵션을 정리하고, 각각의 사용 방법과 실무 활용 사례까지 자세히 알아보겠습니다.
Docker Buildx Build 옵션이란?
Docker Buildx Build 옵션은 이미지 생성 과정을 제어하는 추가 설정입니다.
기본 형식:
docker buildx build [옵션] [경로]예:
docker buildx build \
-t my-app:v1 \
--platform linux/amd64 .옵션을 추가하여 빌드 환경을 원하는 형태로 설정할 수 있습니다.
Docker Buildx Build 주요 옵션 종류
대표적인 옵션:
| 옵션 | 설명 |
|---|---|
| -t | 이미지 이름과 Tag 지정 |
| -f | Dockerfile 지정 |
| –platform | 빌드 플랫폼 지정 |
| –push | Registry Push |
| –load | 로컬 이미지 저장 |
| –cache-from | Cache 가져오기 |
| –cache-to | Cache 저장 |
| –build-arg | 빌드 변수 전달 |
| –progress | 출력 방식 변경 |
-t 옵션 사용법 (이미지 이름 지정)
이미지 이름과 Tag를 지정합니다.
사용법:
docker buildx build \
-t app:v1 .결과:
app:v1운영 환경에서는 버전 Tag 사용을 권장합니다.
예:
docker buildx build \
-t company/app:1.0.0 .-f 옵션 사용법 (Dockerfile 지정)
기본 Dockerfile이 아닌 다른 파일을 사용할 수 있습니다.
예:
docker buildx build \
-f Dockerfile.prod \
-t app:prod .활용:
- 개발 환경
- 테스트 환경
- 운영 환경
Dockerfile을 분리할 때 사용합니다.
–platform 옵션 사용법
멀티 플랫폼 빌드에서 가장 중요한 옵션입니다.
예:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t app:v1 \
--push .생성:
linux/amd64
linux/arm64하나의 이미지 Tag로 여러 환경을 지원합니다.
–push 옵션 사용법
빌드 결과를 Registry에 업로드합니다.
예:
docker buildx build \
-t username/app:v1 \
--push .Docker Hub 또는 Private Registry에 저장됩니다.
멀티 플랫폼 빌드에서는 일반적으로 --push를 사용합니다.
–load 옵션 사용법
빌드 결과를 로컬 Docker 이미지로 저장합니다.
예:
docker buildx build \
-t app:v1 \
--load .확인:
docker images로컬 테스트 환경에서 유용합니다.
–build-arg 옵션 사용법
Dockerfile ARG 변수에 값을 전달합니다.
Dockerfile:
ARG VERSION
RUN echo $VERSION빌드:
docker buildx build \
--build-arg VERSION=1.0 .환경별 빌드 설정에 활용됩니다.
–cache-from 옵션 사용법
기존 Cache를 가져옵니다.
예:
docker buildx build \
--cache-from type=registry,ref=app:cache .CI/CD 빌드 속도를 향상시킵니다.
–cache-to 옵션 사용법
생성된 Cache를 저장합니다.
예:
docker buildx build \
--cache-to type=registry,ref=app:cache .다음 빌드에서 재사용할 수 있습니다.
–progress 옵션 사용법
빌드 출력 형식을 변경합니다.
기본:
docker buildx build .상세 출력:
docker buildx build \
--progress=plain .빌드 오류 분석 시 유용합니다.
Docker Buildx Build 옵션 조합 예제
실무에서 많이 사용하는 형태:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:v1 \
--cache-from type=registry,ref=company/app:cache \
--cache-to type=registry,ref=company/app:cache \
--push .기능:
- 멀티 플랫폼 빌드
- Cache 활용
- Registry Push
까지 한 번에 처리합니다.
Linux 서버 문제 해결
운영 서버에서 Docker 이미지를 빌드했습니다.
명령:
docker buildx build \
-t app:v1 .하지만 다른 서버에서 실행되지 않았습니다.
확인:
docker buildx imagetools inspect app:v1결과:
linux/amd64AMD64 이미지만 생성되었습니다.
해결:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t app:v1 \
--push .다시 확인:
docker buildx imagetools inspect app:v1결과:
linux/amd64
linux/arm64ARM 서버에서도 실행 가능한 이미지가 생성되었습니다.
Docker Buildx Build 옵션 사용 시 주의사항
첫 번째는 --push와 --load는 동시에 사용할 수 없습니다.
두 번째는 멀티 플랫폼 빌드는 일반적으로 Registry Push가 필요합니다.
세 번째는 Cache 설정 시 Tag 관리가 필요합니다.
네 번째는 운영 환경에서는 이미지 Tag 규칙을 명확하게 정해야 합니다.
Best Practice
Docker Buildx Build 옵션 활용 방법:
- 운영 이미지는 버전 Tag 사용
- 멀티 플랫폼은
--platform활용 - CI/CD는 Cache 사용
- 배포 이미지는
--push사용 - 로컬 테스트는
--load사용 - 오류 분석은
--progress=plain활용
자주 묻는 질문
Buildx Build 옵션은 왜 필요한가요?
Docker 이미지 생성 과정을 세밀하게 제어하기 위해 사용합니다.
–push와 –load 차이는 무엇인가요?
--push는 Registry 저장, --load는 로컬 Docker 저장입니다.
멀티 플랫폼 이미지는 어떤 옵션을 사용하나요?
--platform 옵션을 사용합니다.
CI/CD에서 가장 중요한 옵션은 무엇인가요?
일반적으로 --push, Cache 옵션, --platform을 많이 사용합니다.
마무리
Docker Buildx Build 옵션은 단순한 이미지 생성을 넘어 운영 환경에 맞는 Docker 빌드 과정을 구성할 수 있도록 해주는 핵심 기능입니다.
이미지 Tag 관리부터 멀티 플랫폼 빌드, Cache 최적화, Registry Push까지 다양한 작업을 하나의 명령으로 자동화할 수 있습니다.
특히 클라우드 서버, Kubernetes, CI/CD 환경에서는 Buildx 옵션 활용 능력이 안정적인 Docker 운영의 중요한 요소입니다.