Docker 이미지가 잘못 배포됐을 때 빠르게 확인하기

Docker로 배포했는데 코드 변경이 반영이 안 됐다는 불평이 온다. 로컬에선 이미지를 새로 빌드했는데, 실제 운영 서버에선 이전 버전이 떠있었던 경험이 있다.

이미지 태그가 같으면 Docker는 캐시된 이미지를 재사용한다. 그래서 명시적으로 --no-cache 플래그를 안 주거나, 레이어가 변경되지 않으면 새로 빌드하지 않는다.

1단계: 컨테이너 로그 확인

docker logs container-name

# 또는 최근 n줄만
docker logs --tail=50 container-name

# 시간 포함
docker logs --timestamps container-name

컨테이너가 정상 시작했는지 본다. 에러가 있으면 대부분 여기서 나타난다.

만약 코드 변경 이전 버전의 로그가 보인다면, 컨테이너가 이전 이미지로 돌아가고 있다는 뜻이다.

2단계: 실행 중인 이미지 확인

docker ps -a --no-trunc

# 컬럼 보기
docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Names}}"

Image 컬럼에서 이미지명과 태그를 본다. app:latest라고 되어있다면, 최신 태그가 가리키는 실제 이미지가 뭔지 확인해야 한다.

3단계: 이미지 세부 정보

docker inspect image-name:tag

# 또는 짧게
docker images | grep app

Created 시간으로 이미지가 언제 빌드됐는지 본다. 방금 배포했는데 며칠 전 이미지라면, 새로 빌드되지 않은 거다.

4단계: 레이지 이미지 확인

# 실행 중인 컨테이너의 이미지ID
docker inspect container-name | grep 'ImageID'

# 로컬 이미지 목록에서 같은 ID 찾기
docker images --no-trunc | grep <image-id>

Image ID로 정확히 어느 이미지가 돌아가고 있는지 확인한다.

5단계: 캐시된 이미지 제거

# 사용하지 않는 이미지 정리
docker image prune -a

# 또는 특정 이미지만
docker rmi app:old-tag

# 마지막으로 새로 빌드
docker build -t app:latest --no-cache .

--no-cache 플래그가 중요하다. 이 플래그가 없으면 Dockerfile의 각 레이어가 캐시되어, 소스 코드 변경만으로는 새 레이어가 생기지 않을 수 있다.

6단계: 다단계 빌드라면 중간 레이어도 확인

# Dockerfile
FROM node:18 AS builder
COPY . .
RUN npm install
RUN npm run build

FROM node:18-slim
COPY --from=builder /app/dist .
CMD ["node", "dist/index.js"]

Builder 스테이지에서 npm run build가 실행됐는지 로그에서 확인한다. 만약 캐시 히트라면:

Step 4/7 : RUN npm run build
 ---> Using cache
 ---> <image-id>

이렇게 나타난다. 실제 변경된 코드가 빌드에 포함되려면, --no-cache를 써서 이 스테이지를 다시 실행해야 한다.

7단계: 환경 변수와 빌드 시간 설정

docker build -t app:latest \
  --build-arg NODE_ENV=production \
  --build-arg VERSION=$(git rev-parse --short HEAD) \
  .

# 빌드된 이미지에서 확인
docker run app:latest echo $VERSION

빌드 타임 환경 변수나 버전 정보를 이미지에 포함시켜두면, 나중에 어느 커밋이 빌드됐는지 알 수 있다.

8단계: 레지스트리 확인 (Docker Hub, ECR 등 사용 중이라면)

# Docker Hub에서 이미지 확인
docker pull myregistry/app:latest

# 실제 다이제스트 확인
docker inspect myregistry/app:latest | grep 'Digest'

Dockerfile을 수정하고 docker push했는데, 레지스트리의 이미지가 이전 것이라면:

• 푸시가 실패했거나
• 태그가 새 이미지를 가리키지 않음

최종 체크리스트

• 컨테이너 로그 (방금 시작 메시지인가, 몇 시간 전 메시지인가)
• docker ps 의 Image 컬럼 (태그가 맞는가)
• docker images에서 Created 시간 (방금인가, 며칠 전인가)
• docker inspect container의 ImageID (로컬 이미지와 일치하는가)
• 빌드 로그에 Using cache vs 실제 실행 (캐시 여부)

이 다섯 가지로 배포된 이미지가 정말 최신인지 확신할 수 있다.