Docker 이미지를 빌드하면 일반적으로 결과물은 Docker Image 형태로 생성됩니다.
하지만 실제 개발 및 운영 환경에서는 단순히 이미지를 만드는 것 외에도 다양한 형태의 결과물이 필요합니다.
예:
- Docker Image 저장
- Registry Push
- 로컬 파일 출력
- OCI 이미지 생성
- 빌드 결과 파일 추출
- CI/CD Artifact 저장
이러한 빌드 결과의 저장 방식을 제어하기 위해 사용하는 기능이 바로 --output 옵션입니다.
Docker Buildx Build의 --output 옵션은 빌드 결과물을 어떤 형식으로 어디에 저장할지 지정하는 기능입니다.
예:
docker buildx build \
--output type=docker \
-t app:v1 .빌드 결과를 원하는 형태로 관리할 수 있습니다.
이번 글에서는 Docker Buildx Build –output의 개념부터 Output 종류, Docker Image 저장, 파일 출력, Registry 활용, CI/CD 적용 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –output이란 무엇인가?
--output은 Docker Buildx 빌드 결과를 저장하는 방식을 지정하는 옵션입니다.
기본 형식:
docker buildx build \
--output type=출력방식 .빌드 과정:
Dockerfile
↓
Build 실행
↓
결과 생성
↓
지정한 위치로 출력Docker Buildx Build –output이 필요한 이유
기본 Docker Build 결과:
Docker Image하지만 상황에 따라 다른 결과가 필요합니다.
예:
애플리케이션 파일만 필요
↓
local 출력
배포 이미지 필요
↓
registry 출력
테스트용 이미지 필요
↓
docker 출력목적에 맞는 출력 방식을 선택할 수 있습니다.
Docker Buildx Build –output 기본 사용법
예:
docker buildx build \
--output type=docker \
-t app:v1 .Docker Engine에 이미지 형태로 저장합니다.
확인:
docker imagesDocker Buildx Build Output 주요 종류
| Output Type | 설명 |
|---|---|
| docker | Docker 이미지 저장 |
| image | 이미지 생성 |
| registry | Registry 저장 |
| local | 파일 시스템 출력 |
| tar | Tar 파일 생성 |
| oci | OCI 이미지 생성 |
type=docker 사용법
로컬 Docker 이미지로 저장합니다.
예:
docker buildx build \
--output type=docker \
-t test-app:v1 .결과:
Docker Engine
↓
test-app:v1로컬에서 바로 실행할 수 있습니다.
type=registry 사용법
Registry에 이미지를 저장합니다.
예:
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=./result .결과:
result/
├── 파일
└── 생성 결과정적 파일 생성이나 Artifact 저장에 활용합니다.
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 .컨테이너 표준 형식으로 관리할 수 있습니다.
Docker Buildx Build –output과 –load 차이
비슷해 보이지만 목적이 다릅니다.
–load
docker buildx build \
--load \
-t app:v1 .목적:
- Docker Engine으로 이미지 가져오기
- 로컬 테스트
–output
docker buildx build \
--output type=local,dest=./result .목적:
- 다양한 형태 출력
- 파일 저장
- 결과 관리
정리:
--load
= 로컬 Docker 이미지 저장
--output
= 결과 저장 방식 지정Docker Buildx Build –output 실무 활용 예제
CI/CD Artifact 생성
빌드:
docker buildx build \
--output type=local,dest=./artifact .결과:
artifact/
↓
CI 저장 파일배포 과정에서 사용할 수 있습니다.
정적 웹 사이트 빌드 활용
Dockerfile:
FROM node
RUN npm install
RUN npm run build출력:
docker buildx build \
--output type=local,dest=./dist .생성:
dist/
├── index.html
└── assets빌드 결과 파일만 가져올 수 있습니다.
Linux 서버 문제 해결
Docker 빌드 후 이미지가 아닌 결과 파일이 필요했습니다.
기존:
docker buildx build \
-t app:v1 .문제:
이미지만 생성됨
파일 결과 없음해결:
docker buildx build \
--output type=local,dest=./build-result .결과:
build-result/
↓
필요한 파일 생성원하는 결과물을 얻을 수 있었습니다.
Docker Buildx Build –output 사용 시 주의사항
첫 번째는 Output Type에 따라 결과가 완전히 달라집니다.
두 번째는 멀티 플랫폼 빌드에서는 Output 방식 선택이 중요합니다.
세 번째는 Registry 저장과 로컬 저장 목적을 구분해야 합니다.
네 번째는 CI/CD 환경에서는 결과 경로 관리가 필요합니다.
Best Practice
Docker Buildx Build –output 활용 방법:
- 로컬 테스트는 type=docker 활용
- 파일 추출은 type=local 사용
- 운영 배포는 Registry 활용
- OCI 필요 시 type=oci 사용
- CI Artifact 저장 활용
- 목적에 맞는 Output 선택
자주 묻는 질문
Docker Buildx Build –output은 무엇인가요?
Docker 빌드 결과물을 원하는 방식으로 저장하는 옵션입니다.
이미지를 저장할 수도 있나요?
가능합니다.
type=docker, type=registry 등을 사용할 수 있습니다.
파일 형태 결과도 만들 수 있나요?
가능합니다.
type=local을 사용하면 됩니다.
CI/CD에서 사용할 수 있나요?
네.
빌드 결과 파일 저장과 배포 자동화에 활용됩니다.
마무리
Docker Buildx Build –output은 Docker 빌드 결과를 다양한 형태로 관리할 수 있게 해주는 중요한 옵션입니다.
단순히 Docker 이미지를 생성하는 것을 넘어 파일 출력, Registry 저장, OCI 이미지 생성 등 다양한 목적에 맞게 결과물을 관리할 수 있습니다.
특히 CI/CD 환경에서는 빌드 결과물을 Artifact로 저장하거나 배포 단계와 연결할 수 있어 자동화된 Docker 운영 환경 구축에 매우 유용합니다.