Docker 이미지를 빌드하면 일반적으로 결과물이 Docker Image 형태로 생성됩니다.
하지만 실제 개발 및 운영 환경에서는 다양한 형태의 결과물이 필요할 수 있습니다.
예:
- Docker Image로 저장
- Registry Push
- 로컬 파일로 저장
- Docker RootFS 추출
- OCI 이미지 생성
- 특정 Build 결과만 출력
이때 사용하는 기능이 바로 Docker Buildx Build –output 옵션입니다.
--output 옵션은 Docker Buildx 빌드 결과물을 어디에 어떤 형식으로 저장할지 지정하는 기능입니다.
예:
docker buildx build \
--output type=docker \
-t app:v1 .빌드 결과를 원하는 형태로 출력할 수 있습니다.
이번 글에서는 Docker Buildx Build –output의 개념부터 주요 Output 유형, 사용 방법, Registry 저장, 파일 출력, 실무 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –output이란 무엇인가?
--output은 Buildx 빌드 결과의 저장 방식을 지정하는 옵션입니다.
기본 형식:
docker buildx build \
--output type=출력방식 .Build 결과:
Docker Image
↓
Output Exporter
↓
원하는 저장 위치로 전달됩니다.
Docker Buildx Build –output은 언제 사용하는가?
다음과 같은 상황에서 사용합니다.
- 이미지 저장 방식 변경
- CI/CD 결과 관리
- OCI 이미지 생성
- 로컬 테스트
- 파일 형태 결과 저장
- 배포 자동화
특히 BuildKit 기반 환경에서는 중요한 기능입니다.
Docker Buildx Build Output 주요 유형
대표적인 Output 방식:
| Output Type | 설명 |
|---|---|
| docker | Docker Engine 이미지 저장 |
| image | 이미지 생성 |
| registry | Registry Push |
| local | 파일 시스템 출력 |
| tar | Tar 파일 출력 |
| oci | OCI 이미지 출력 |
type=docker 사용법
Docker Engine 이미지로 저장합니다.
예:
docker buildx build \
--output type=docker \
-t app:v1 .확인:
docker images로컬 Docker 이미지로 사용할 수 있습니다.
type=image 사용법
이미지를 생성합니다.
예:
docker buildx build \
--output type=image \
-t app:v1 .이미지 결과를 생성하지만 저장 방식은 추가 설정에 따라 달라집니다.
type=registry 사용법
Registry에 Push합니다.
예:
docker buildx build \
--output type=registry \
-t company/app:v1 .또는 일반적으로:
docker buildx build \
-t company/app:v1 \
--push .방식을 더 많이 사용합니다.
type=local 사용법
빌드 결과를 로컬 폴더에 저장합니다.
예:
docker buildx build \
--output type=local,dest=./output .결과:
output/
├── 파일
└── 결과 데이터정적 파일 생성 등에 활용할 수 있습니다.
type=tar 사용법
Tar 파일 형태로 출력합니다.
예:
docker buildx build \
--output type=tar,dest=image.tar .결과:
image.tar파일 형태로 전달할 수 있습니다.
type=oci 사용법
OCI 이미지 형식으로 저장합니다.
예:
docker buildx build \
--output type=oci,dest=image.tar .OCI 표준 이미지 포맷으로 생성됩니다.
Docker Buildx Build –output과 –push 차이
두 옵션은 비슷해 보이지만 목적이 다릅니다.
–push
docker buildx build \
-t app:v1 \
--push .목적:
- Registry 업로드
- 운영 배포
–output
docker buildx build \
--output type=local,dest=./result .목적:
- 결과 저장 방식 제어
- 파일 출력
- 사용자 지정 저장
Docker Buildx Build –output 실무 활용 예제
로컬 Docker 이미지 테스트
명령:
docker buildx build \
--output type=docker \
-t test-app:v1 .확인:
docker images test-app실행:
docker run test-app:v1로컬 테스트 환경에서 사용할 수 있습니다.
CI/CD 결과 파일 생성
빌드 결과물을 파일로 저장:
docker buildx build \
--output type=local,dest=./build-result .CI 작업 결과물로 보관할 수 있습니다.
Linux 서버 문제 해결
CI 서버에서 Docker Buildx 빌드를 실행했습니다.
명령:
docker buildx build \
-t app:v1 .빌드는 성공했지만 결과 파일이 필요했습니다.
기본 방식에서는 원하는 결과물이 생성되지 않았습니다.
해결:
docker buildx build \
--output type=local,dest=./artifact .확인:
ls artifact결과:
build-result files필요한 파일을 CI Artifact로 저장할 수 있었습니다.
Docker Buildx Build –output은 빌드 결과를 원하는 형태로 관리하는 핵심 기능입니다.
Docker Buildx Build –output 사용 시 주의사항
첫 번째는 Output Type에 따라 결과 형태가 달라집니다.
두 번째는 멀티 플랫폼 이미지에서는 Output 방식 선택이 중요합니다.
세 번째는 로컬 저장과 Registry Push 목적을 구분해야 합니다.
네 번째는 CI/CD에서는 결과 경로 관리가 필요합니다.
Best Practice
Docker Buildx Build –output 활용 방법:
- 로컬 테스트는 type=docker 사용
- 운영 배포는 type=registry 활용
- 파일 결과물은 type=local 사용
- OCI 표준 필요 시 type=oci 사용
- CI Artifact 저장에 활용
- 빌드 목적에 맞는 Output 선택
자주 묻는 질문
Docker Buildx Build –output은 무엇인가요?
빌드 결과를 어디에 어떤 형식으로 저장할지 지정하는 옵션입니다.
–output과 –push 차이는 무엇인가요?
–push는 Registry 업로드, –output은 다양한 출력 방식을 지정합니다.
로컬 이미지로 저장하려면 어떻게 하나요?
--output type=docker옵션을 사용합니다.
파일 형태로 결과를 만들 수 있나요?
가능합니다.
--output type=local을 사용할 수 있습니다.
마무리
Docker Buildx Build –output은 Docker 빌드 결과를 다양한 형태로 관리할 수 있게 해주는 강력한 기능입니다.
단순히 이미지를 생성하는 것을 넘어 로컬 Docker 저장, Registry 업로드, 파일 출력, OCI 이미지 생성 등 다양한 빌드 결과 관리가 가능합니다.
특히 CI/CD 환경에서는 빌드 결과물을 원하는 형태로 저장하고 전달할 수 있어 자동화 파이프라인 구축에 매우 유용합니다.