🐳Dockerfile 빌드 최적화하기 - BuildKit, Multi-Stage

안녕하세요~

 

이번에는 제가 Dockerfile 을 사용할 때 노가다를 해보면서 얻은 빌드 전략과 방식에 대해서 소개해드리겠습니다!

먼저 Dockerfile 이란 

빌드 자동화 도구이자 CI/CD 핵심 구성 요소 역할을 합니다.

프로젝트가 커지고 빌드 대상이 많이질수록 Dockerfile 구조, 빌드 방식, 캐시 전략은 성능과 유지보수에 큰 영향을 줍니다.

 

이 글에서는 Dockerfile 을 효율적으로 작성하는 방법, 그리고 BuildKit 기반 고속 빌드 전략과 에러 이후 재빌드가 어떻게 동작하는지 까지 제가 실제로 겪었던 고충을 해결하는 방법을 정리하였습니다

 

📌 1. Dockerfile 빌드 구조의 기본 개념

Dockerfile은 위에서 아래로 순차적으로 실행되며, 각 명령은 레이어(layer)를 형성합니다.

형태	설명
FROM	새 스테이지 시작
RUN	명령 실행 후 결과물을 레이어로 저장
COPY / ADD	파일/디렉터리 복사, 새로운 레이어 생성
ENV / ARG	환경 설정, 빌드 옵션 정의
CMD / ENTRYPOINT	실행 컨테이너의 시작점 정의

★ Dockerfile 을 수정하면, 변경된 라인과 그 아래의 캐시는 모두 초기화 됩니다.

그렇기 때문에 Dockerfile을 설계할 때에는 변경 가능성과 캐시를 고려하여 구조화하는것이 매우 중요합니다!

 

🧱 2. Multi-Stage Build

Multi-Stage 빌드는 복잡한 빌드 과정에서 필요한 단계들을 여러 개의 스테이지로 분리하는 방식입니다.

# 예시 코드
FROM ubuntu:22.04 AS build-env
RUN apt update && apt install -y build-essential

FROM build-env AS build-app
RUN make && make install

FROM ubuntu:22.04 AS runtime
COPY --from=build-app /usr/local/bin/myapp /usr/local/bin/myapp
CMD ["myapp"]

 

Multi-Stage 빌드의 장점

장점	설명
이미지 크기 최소화	빌드 도구를 최종 이미지에 포함하지 않음
유지보수 용이	단계별 역할 분리
디버깅 용이	실패 지점 명확
재빌드 시 캐시 활용 극대화	스테이지 단위 캐시 적용 가능

Multi-Stage 가 특히 유용한 이유는 프로젝트가 커질수록 빌드 스테이지 단위로 문제 추적, 재빌드 비용 감소 가능하기 때문입니다!

 

⚡ 3. BuildKit — 더 빠른 빌드 엔진 사용하기

BuildKit 활성화

BuildKit 을 활성화하는 방법은 2가지가 있습니다.

 

① docker build 전 DOCKER_BUILDKIT=2 을 export 

export DOCKER_BUILDKIT=1
docker build .

 

② Dockerfile의 첫 줄에 아래 # syntax 명령어 추가

# syntax=docker/dockerfile:1.7

 

이렇게 간단하게 명령어를 추가함으로써 BuildKit 을 사용할 수 있지만 이로 인해서 얻는 장점은 다양합니다!

 

 

BuildKit으로 얻는 개선점

항목	설명
병렬 빌드 처리	기존 Docker보다 월등히 빠름
고급 캐시 재사용	레이어 캐시 활용 방식 향상
--mount=type=cache 등 빌드 캐시 마운트 기능 제공
SSH forwarding / secret 지원	Private repo 빌드에 유용

 

🔁 4. 빌드 도중 에러 시 재빌드 (BuildKit 을 사용하면서 가장 편리해진 부분)

Dockerfile 빌드 시 BuildKit을 사용하면 빌드를 실패하더라도 Dockerfile 의 에러가 발생한 지점부터 다시 재실행 할 수 있습니다!

 

BuildKit 은 이전 레이어까지는 캐시를 사용하여 스킵이 되고,

에러가 발생하거나 변경된 이후 단계부터 다시 실행하게 됩니다.

 

예시:

RUN apt update && apt install -y gcc 
RUN ./configure && make && make install 
RUN echo "complete"

 

만약 두 번째 RUN에서 실패하고 Dockerfile을 수정 후 다시 빌드하면:

#1 RUN apt update ... -> CACHED
#2 RUN ./configure -> 재실행
#3 RUN echo "complete" -> 이후 단계 다시 실행

 

정리

항목	동작
동일한 명령 라인	캐시 사용
수정된 명령 이후	모두 재빌드
RUN 내부 명령 하나만 재실행	❌ 전체 RUN 줄이 다시 실행
완전한 resume build	❌ (CI 도구에서만 가능)

 

🔧 5. 결론 및 정리

 

Dockerfile 을 활용할 때에는 빌드 속도 및 캐시를 잘 활용하자!

전략	이유
자주 바뀌는 부분을 Dockerfile 아래 위치	캐시 활용 극대화
Multi-Stage로 빌드 분리	변경 범위 최소화
패키지 업데이트 & 설치 묶기	레이어 수 최소화
--mount=type=cache 사용	컴파일 반복 속도 향상
COPY 전에 .dockerignore 구성	불필요한 파일 이동 방지

 

지금까지 Dockerfile 을 Build 할 때 BuildKit과 Multi-Stage 를 통해
캐시를 극대화 하고 빌드를 편하게 할 수 있는 방법에 대해서 알아보았습니다!

 

제가 처음부터 BuildKit 캐시재사용 방식을 알았더라면 더 빠르게 작업들을 끝낼 수 있었을 탠데...

좋은 빌드 방식을 알게 되어 게시글을 이렇게 작성하게 되었습니다!

 

마지막으로 빌드 명령어 예시 전달드리며 게시글 마칩니다