Docker Image를 Build할 때 터미널에는 다양한 진행 정보가 표시됩니다.

예:

[+] Building 45.3s (10/10)

=> [internal] load Dockerfile

=> [1/5] FROM ubuntu

=> [2/5] RUN apt update

=> exporting image

이러한 Build 출력 방식은 Docker Buildx에서 progress 옵션으로 변경할 수 있습니다.

Docker Buildx Bake에서는 Build 진행 화면을 원하는 형태로 설정할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  output = [
    "type=registry"
  ]

  progress = "plain"

}

실행:

docker buildx bake app

결과:

Build 과정 상세 출력

↓

명령어별 실행 결과 표시

이번 글에서는 Docker Buildx Bake Progress의 개념부터 출력 방식 종류, CI/CD 로그 관리, 디버깅 활용 방법까지 자세히 알아보겠습니다.

Table of Contents

Docker Buildx Bake Progress란 무엇인가?

Docker Buildx Bake Progress는 Docker Build 과정에서 표시되는 진행 화면 형식을 설정하는 기능입니다.

기본 구조:

Docker Build 실행

↓

Build 단계 진행

↓

Progress 출력 방식 적용

Progress 설정을 통해 Build 로그를 사람이 보기 쉽게 표시하거나 CI 시스템에서 분석하기 좋은 형태로 변경할 수 있습니다.

Docker Buildx Bake Progress가 필요한 이유

기본 Build 출력:

[+] Building 30.5s

=> Step 실행

=> Layer 생성

=> Image Export

문제:

CI 로그 분석 어려움
오류 위치 확인 어려움
상세 Build 과정 확인 부족

Progress 변경:

Build 단계

↓

각 명령 실행 결과 표시

↓

문제 위치 확인 가능

장점:

디버깅 편리
CI 로그 관리 개선
Build 상태 확인 용이

Docker Buildx Bake Progress 기본 설정

docker-bake.hcl:

target "app" {

  progress = "plain"

}

실행:

docker buildx bake app

출력:

#1 [internal] load Dockerfile

#2 [1/5] FROM ubuntu

#3 RUN npm install

#4 exporting image

각 Build 단계가 상세하게 표시됩니다.

Docker Buildx Bake Progress 종류

Docker Buildx에서 사용하는 주요 Progress 방식은 다음과 같습니다.

auto

기본 설정입니다.

예:

docker buildx bake app --progress auto

특징:

터미널 환경 자동 판단
일반 개발 환경 적합

출력:

깔끔한 Build 화면

plain

상세 로그 출력 방식입니다.

설정:

docker buildx bake app --progress plain

특징:

모든 Build 단계 표시
오류 분석 용이
CI 환경 추천

출력:

#1 FROM ubuntu

#2 RUN apt update

#3 COPY .

tty

터미널 전용 출력 방식입니다.

예:

docker buildx bake app --progress tty

특징:

실시간 화면 업데이트
로컬 개발 환경 적합

출력:

[=======>      ] 70%

quiet

출력을 최소화합니다.

예:

docker buildx bake app --progress quiet

특징:

불필요한 로그 숨김
자동화 환경 활용

Docker Buildx Bake Progress 명령어 사용법

일회성 변경:

docker buildx bake app --progress plain

CI 디버깅:

docker buildx bake production --progress plain

출력을 줄일 때:

docker buildx bake app --progress quiet

Docker Buildx Bake Progress와 CI/CD 활용

CI 환경에서는 상세 로그가 매우 중요합니다.

기본 출력:

Build 실패

↓

원인 확인 어려움

plain 사용:

docker buildx bake production --progress plain

결과:

실행 명령 확인

↓

실패 위치 확인

↓

문제 해결

GitHub Actions 예:

- name: Build Docker Image

  run: |

    docker buildx bake production --progress plain

Docker Buildx Bake Progress와 Debug 활용

Build 오류 발생 시 가장 먼저 사용하는 옵션입니다.

예:

오류:

RUN npm install failed

Progress plain:

#5 RUN npm install

npm ERR!
package not found

문제 위치를 바로 확인할 수 있습니다.

Docker Buildx Bake Progress와 로그 관리

대규모 프로젝트에서는 Build 로그 관리가 중요합니다.

plain 방식:

전체 Build 기록 저장 가능

활용:

Jenkins 로그
GitLab Pipeline 로그
GitHub Actions 로그
장애 분석

Docker Buildx Bake Progress CI/CD 실무 설정

GitLab CI 예:

build:

  stage: build

  script:

    - docker buildx bake production --progress plain

결과:

Pipeline 실행

↓

상세 Build 로그 저장

↓

문제 분석 가능

Docker Buildx Bake Progress 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── .gitlab-ci.yml

docker-bake.hcl:

target "production" {

  tags = [
    "registry.company.com/app:v1"
  ]

  progress = "plain"

}

실행:

docker buildx bake production

결과:

Build 단계 표시

↓

오류 확인 쉬움

↓

Image 생성

Docker Buildx Bake Progress 문제 해결

출력이 너무 복잡한 경우

사용:

docker buildx bake app --progress auto

기본 출력으로 변경합니다.

CI 로그가 부족한 경우

사용:

docker buildx bake app --progress plain

상세 정보를 확인합니다.

터미널 화면이 깨지는 경우

사용:

docker buildx bake app --progress plain

TTY 출력을 제거합니다.

Docker Buildx Bake Progress 사용 시 주의사항

첫 번째는 CI 환경에서는 plain 출력이 문제 해결에 유리합니다.

두 번째는 로그가 길어질 수 있으므로 저장 정책이 필요합니다.

세 번째는 일반 개발 환경에서는 auto 또는 tty가 편리합니다.

네 번째는 Secret 정보가 로그에 출력되지 않는지 확인해야 합니다.

Best Practice

Docker Buildx Bake Progress 활용 방법:

개발 환경은 auto 사용
CI/CD는 plain 사용
오류 분석 시 plain 활용
로그 저장 정책 관리
Secret 출력 확인
Build 상태 모니터링

자주 묻는 질문

Docker Buildx Bake Progress는 무엇인가요?

Docker Build 과정의 출력 방식을 설정하는 기능입니다.

가장 많이 사용하는 설정은 무엇인가요?

개발 환경은 auto, CI/CD 환경은 plain 방식을 많이 사용합니다.

Build 오류 확인에 도움이 되나요?

가능합니다.

plain 모드를 사용하면 실행 단계와 오류 위치를 자세히 확인할 수 있습니다.

Quiet 모드는 언제 사용하나요?

자동화 환경에서 불필요한 로그를 줄일 때 사용합니다.

마무리

Docker Buildx Bake Progress는 Docker Build 과정을 효율적으로 확인하기 위한 중요한 기능입니다.

개발 환경에서는 깔끔한 출력 화면을 제공하고, CI/CD 환경에서는 상세 로그를 통해 오류 분석과 장애 해결을 쉽게 만들어 줍니다.

특히 Docker Image 자동 빌드 환경에서는 상황에 맞는 Progress 설정을 사용하면 더욱 효율적인 Build 관리가 가능합니다.

Docker Buildx Bake Progress 사용법 완벽 가이드! Build 출력 방식 변경하기