Docker 이미지를 빌드하다 보면 단순히 성공 또는 실패 여부만 확인하는 것이 아니라, 정확히 어느 단계에서 문제가 발생했는지 분석해야 하는 상황이 발생합니다.
특히 운영 환경에서는 다음과 같은 문제가 자주 발생합니다.
- 특정 Dockerfile 단계에서 빌드 실패
- 이전 빌드와 결과 비교 필요
- 빌드 시간이 갑자기 증가
- Cache 사용 여부 확인 필요
- CI/CD 빌드 오류 분석
이럴 때 사용하는 기능이 바로 Docker Buildx History Inspect입니다.
Docker Buildx History Inspect는 특정 빌드 기록의 상세 정보를 확인하는 명령어입니다.
빌드 단계, 실행 시간, 오류 발생 위치, 사용된 Cache 정보 등을 확인할 수 있어 Docker 이미지 생성 과정을 분석하는 데 매우 유용합니다.
이번 글에서는 Docker Buildx History Inspect의 개념부터 기본 사용법, 출력 정보 확인 방법, 빌드 오류 분석, 실무 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx History Inspect란 무엇인가?
Docker Buildx History Inspect는 특정 Build 기록의 상세 정보를 조회하는 기능입니다.
docker buildx history ls가 전체 빌드 목록을 확인하는 명령이라면,
docker buildx history inspect는 특정 빌드를 자세히 분석하는 명령입니다.
확인 가능한 정보:
- Build ID
- Dockerfile 실행 단계
- 빌드 시간
- Cache 사용 여부
- 오류 발생 단계
- 빌드 결과
Docker Buildx History Inspect는 언제 사용하는가?
다음과 같은 상황에서 활용합니다.
- 빌드 실패 원인 분석
- Dockerfile 단계 확인
- CI/CD 오류 해결
- 빌드 성능 분석
- Cache 문제 확인
특히 복잡한 Docker 프로젝트에서는 필수적인 분석 도구입니다.
Docker Buildx History Inspect 기본 사용법
먼저 빌드 기록을 확인합니다.
docker buildx history ls출력:
BUILD ID STATUS
abc123 DONE
def456 ERROR상세 확인할 Build ID를 선택합니다.
docker buildx history inspect abc123해당 빌드의 상세 정보가 출력됩니다.
Docker Buildx History Inspect 출력 정보 확인하기
예시:
Build ID:
abc123
Status:
DONE
Created:
2026-07-27
Duration:
45s빌드 실행 정보를 확인할 수 있습니다.
Build ID
빌드 작업의 고유 식별자입니다.
예:
abc123특정 빌드를 조회할 때 사용합니다.
Status
빌드 결과 상태입니다.
예:
DONE성공적으로 완료된 빌드입니다.
또는:
ERROR빌드 실패 상태입니다.
Duration
빌드에 걸린 시간입니다.
예:
45s이전 빌드와 비교하여 성능 변화를 확인할 수 있습니다.
Dockerfile 빌드 단계 확인하기
Inspect를 활용하면 각 Dockerfile 단계 정보를 확인할 수 있습니다.
예:
Step 1/6 FROM node:20
Step 2/6 COPY package.json
Step 3/6 RUN npm install
Step 4/6 COPY .
Step 5/6 RUN npm build어느 단계에서 시간이 오래 걸리는지 확인할 수 있습니다.
실패한 빌드 상세 분석하기
실패한 Build ID 확인:
docker buildx history ls예:
BUILD ID
xyz789 ERROR상세 확인:
docker buildx history inspect xyz789출력:
Step 3/6
RUN npm install
ERROR:
package not found문제가 발생한 단계를 정확하게 확인할 수 있습니다.
Docker Buildx History Inspect와 Cache 분석
빌드 속도가 느려졌다면 Cache 사용 여부를 확인할 수 있습니다.
확인 항목:
- Cache Hit
- 다시 실행된 단계
- 변경된 Layer
예:
COPY source files
Cache:
missCache가 적용되지 않은 단계를 찾을 수 있습니다.
Docker Buildx History Inspect 실무 활용 예제
빌드 시간이 증가한 문제 분석
기존 빌드:
Duration:
30s최근 빌드:
Duration:
5m원인을 찾기 위해:
docker buildx history ls최근 Build ID 확인:
docker buildx history inspect abc123결과:
Step 4/7
RUN apt install package해당 단계에서 시간이 증가한 것을 확인했습니다.
CI/CD 실패 원인 확인
자동 배포 실패:
Build failed빌드 기록 확인:
docker buildx history ls상세 분석:
docker buildx history inspect build-id결과:
COPY failed:
file not foundDockerfile 경로 문제를 확인할 수 있습니다.
Linux 서버 문제 해결
운영 서버에서 Docker 이미지 배포가 실패했습니다.
기존 로그에서는 단순히:
BUILD FAILED만 표시되었습니다.
관리자는 Build History를 확인했습니다.
docker buildx history ls실패한 Build ID 확인:
abc456 ERROR상세 분석:
docker buildx history inspect abc456결과:
Step 5/8
RUN npm run build
ERROR:
command failed확인 결과 Node 환경 설정 문제가 원인이었습니다.
환경 수정 후 다시 빌드했습니다.
docker buildx build -t app:v2 .정상적으로 이미지 생성이 완료되었습니다.
Docker Buildx History Inspect를 활용하면 단순 오류 메시지가 아닌 정확한 실패 위치를 확인할 수 있습니다.
Docker Buildx History Inspect 사용 시 주의사항
첫 번째는 Inspect는 빌드 분석용 명령어입니다.
이미지를 수정하거나 다시 생성하지 않습니다.
두 번째는 Build ID를 정확하게 입력해야 합니다.
세 번째는 오래된 빌드 기록은 환경 설정에 따라 유지되지 않을 수 있습니다.
네 번째는 민감한 빌드 정보가 기록되지 않도록 Dockerfile 관리에 주의해야 합니다.
Best Practice
Docker Buildx History Inspect를 사용할 때는 다음 방법을 추천합니다.
- 실패한 빌드는 Inspect로 분석합니다.
- 빌드 시간 변화를 비교합니다.
- Dockerfile 변경 후 결과를 확인합니다.
- CI/CD 오류 분석에 활용합니다.
- Cache 문제 발생 시 확인합니다.
- 중요한 배포 전 빌드 기록을 확인합니다.
자주 묻는 질문
Docker Buildx History Inspect는 무엇인가요?
특정 Docker 빌드 기록의 상세 정보를 확인하는 기능입니다.
History와 Inspect 차이는 무엇인가요?
History는 목록 확인, Inspect는 상세 분석입니다.
Inspect로 실패한 빌드를 다시 실행할 수 있나요?
아닙니다.
빌드 과정 확인과 분석만 가능합니다.
빌드 시간도 확인할 수 있나요?
가능합니다.
Duration 정보를 통해 빌드 시간을 확인할 수 있습니다.
마무리
Docker Buildx History Inspect는 Docker 빌드 과정을 상세하게 분석하는 중요한 관리 기능입니다.
빌드 실패 원인을 찾거나 성능 저하 문제를 해결할 때 단순 로그보다 더 자세한 정보를 확인할 수 있습니다.
특히 CI/CD 환경에서는 빌드 기록 분석이 매우 중요하며, docker buildx history ls와 docker buildx history inspect를 함께 활용하면 안정적인 Docker 이미지 운영이 가능합니다.