Docker 이미지를 빌드하면 터미널 화면에 다양한 진행 과정이 표시됩니다.
예:
[+] Building 15.3s
=> [internal] load build definition
=> [1/5] FROM ubuntu
=> [2/5] RUN apt update
=> exporting layers이러한 출력 정보는 빌드 상태를 확인하는 데 유용하지만, CI/CD 환경이나 로그 관리 환경에서는 원하는 형태로 변경해야 하는 경우가 있습니다.
Docker Buildx Build에서는 빌드 진행 상황 출력 방식을 제어할 수 있는 옵션을 제공합니다.
바로 --progress 옵션입니다.
예:
docker buildx build \
--progress plain \
-t app:v1 .빌드 로그 표시 방식을 변경할 수 있습니다.
이번 글에서는 Docker Buildx Build –progress의 개념부터 출력 방식 종류, CI/CD 로그 관리, 디버깅 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –progress란 무엇인가?
--progress는 Docker Buildx 빌드 과정에서 표시되는 진행 상태 출력 방식을 지정하는 옵션입니다.
기본 형식:
docker buildx build \
--progress 출력방식 .빌드 과정:
Docker Build 실행
↓
BuildKit 진행 정보 생성
↓
지정한 형식으로 출력Docker Buildx Build –progress가 필요한 이유
기본 출력 방식은 개발 환경에서는 보기 편하지만 CI 환경에서는 문제가 될 수 있습니다.
문제:
로그 확인 어려움
실행 과정 추적 어려움
에러 위치 확인 어려움--progress를 사용하면 상황에 맞는 출력 형식을 선택할 수 있습니다.
Docker Buildx Build –progress 주요 옵션
대표적인 출력 방식:
| 옵션 | 설명 |
|---|---|
| auto | 환경에 따라 자동 선택 |
| tty | 터미널용 출력 |
| plain | 일반 텍스트 로그 |
| quiet | 결과만 표시 |
–progress auto 사용법
기본 설정입니다.
예:
docker buildx build \
--progress auto \
-t app:v1 .환경에 따라 적절한 출력 방식을 자동 선택합니다.
일반적인 로컬 개발 환경에서는 기본값으로 충분합니다.
–progress tty 사용법
터미널 화면에 최적화된 출력 방식입니다.
예:
docker buildx build \
--progress tty \
-t app:v1 .출력:
[+] Building 20.5s
=> STEP 1/5
=> STEP 2/5개발자가 실시간 진행 상황을 확인할 때 적합합니다.
–progress plain 사용법
모든 빌드 로그를 일반 텍스트 형태로 출력합니다.
예:
docker buildx build \
--progress plain \
-t app:v1 .출력:
#1 [internal] load Dockerfile
#2 RUN apt update
#3 COPY .장점:
- 로그 저장 용이
- CI 환경 적합
- 오류 분석 편리
Docker Buildx Build –progress 실무 활용 예제
CI/CD 로그 관리
CI 환경에서는:
docker buildx build \
--progress plain \
-t company/app:v1 \
--push .사용합니다.
장점:
- 전체 로그 기록 가능
- 실패 원인 확인 쉬움
- 자동 분석 가능
Docker Build 오류 분석
빌드 실패:
docker buildx build \
-t app:v1 .출력이 복잡해 오류 확인이 어렵습니다.
변경:
docker buildx build \
--progress plain \
-t app:v1 .결과:
RUN npm install
ERROR package not found정확한 실패 위치를 확인할 수 있습니다.
Docker Buildx Build –progress와 CI/CD 활용
GitHub Actions 예:
- name: Build Docker Image
run: |
docker buildx build \
--progress plain \
-t app:v1 .빌드 로그가 일반 텍스트로 저장됩니다.
Linux 서버 문제 해결
Docker 빌드가 실패했지만 원인을 확인하기 어려웠습니다.
기존:
docker buildx build \
-t app:v1 .문제:
출력이 화면 갱신 방식이라 로그 확인 어려움해결:
docker buildx build \
--progress plain \
-t app:v1 .확인:
RUN apt install
ERROR dependency failed실패 원인을 쉽게 찾을 수 있었습니다.
Docker Buildx Build –progress 사용 시 주의사항
첫 번째는 plain 출력은 로그 양이 많아질 수 있습니다.
두 번째는 로컬 개발 환경에서는 tty 방식이 더 보기 편할 수 있습니다.
세 번째는 CI 환경에서는 일반적으로 plain 사용을 권장합니다.
네 번째는 로그 저장 정책을 함께 관리해야 합니다.
Best Practice
Docker Buildx Build –progress 활용 방법:
- 로컬 개발은 auto 또는 tty 사용
- CI/CD는 plain 사용
- 오류 분석 시 plain 활용
- 로그 보관 정책 설정
- 자동화 환경에 맞는 출력 선택
- 빌드 시간과 로그 크기 관리
자주 묻는 질문
Docker Buildx Build –progress는 무엇인가요?
Docker 빌드 진행 상황 출력 방식을 변경하는 옵션입니다.
CI/CD에서는 어떤 옵션을 사용하나요?
일반적으로 plain 옵션을 많이 사용합니다.
plain과 tty 차이는 무엇인가요?
tty는 실시간 화면 표시, plain은 저장 가능한 일반 로그 형식입니다.
기본값은 무엇인가요?
auto 방식으로 환경에 따라 자동 선택됩니다.
마무리
Docker Buildx Build –progress는 Docker 이미지 빌드 과정의 출력 방식을 제어하는 유용한 옵션입니다.
개발 환경에서는 보기 좋은 tty 방식이 편리하고, CI/CD 환경에서는 모든 로그를 기록할 수 있는 plain 방식이 효과적입니다.
특히 빌드 오류 분석이나 자동화 파이프라인에서는 적절한 Progress 설정을 통해 문제 해결 시간을 크게 줄일 수 있습니다.