Reference

Opening reference

Preparing the article, table of contents, and metadata. 본문, 목차, 메타데이터를 준비하고 있습니다.

Loading category cards

Preparing references and filters for this topic. 이 주제의 레퍼런스와 필터를 준비하고 있습니다.

Docker이미지와 빌드

image tag와 push

이미지 이름과 태그가 버전 식별과 배포 경로를 결정한다는 점을 중심으로 build, tag, push 흐름을 정리합니다.

마지막 수정 2026년 4월 2일

빠른 흐름

bash

docker build -t myname/my-app:1.2.3 .
docker push myname/my-app:1.2.3

기본 흐름

어떤 태그와 배포 기준을 먼저 떠올리면 되나

상황	먼저 떠올릴 선택
재현 가능한 배포 버전 필요	시맨틱 버전 또는 SHA 태그
정확한 이미지 고정이 중요	다이제스트 pull
편의용 최신 별칭 유지	`latest`는 보조 태그로만 사용
레지스트리 업로드	`docker login` → `build/tag/push`

태그가 이미지 다이제스트(SHA256)에 대한 가변 포인터인 이유

이미지의 실제 식별자는 콘텐츠 기반으로 계산된 SHA256 다이제스트다. 태그는 이 다이제스트에 붙이는 사람이 읽을 수 있는 별칭이다. 태그는 언제든 다른 다이제스트로 바뀔 수 있다. docker pull my-app:1.0.0을 두 번 실행해도 사이에 태그가 재지정됐다면 서로 다른 이미지를 받을 수 있다.

bash

# 다이제스트로 정확한 버전을 고정해서 pull
docker pull myname/my-app@sha256:abc123...

# 이미지의 실제 다이제스트 확인
docker inspect --format='{{index .RepoDigests 0}}' myname/my-app:1.2.3

latest 태그의 위험성과 재현 불가능한 빌드

latest는 Docker가 자동으로 관리하는 특별한 태그가 아니다. 사람이 명시적으로 붙이지 않으면 자동으로 붙는 기본값일 뿐이며, 어떤 이미지가 latest인지는 레지스트리에 마지막으로 push한 사람에게 달려 있다. 팀에서 latest만 사용하면 어떤 코드가 배포됐는지 추적이 불가능해진다.

bash

# latest만 push하면 어떤 빌드인지 추적 불가
docker push myname/api:latest  # 피해야 할 패턴

# 명시적 버전 + latest를 함께 push (latest는 편의용 별칭)
docker push myname/api:1.2.3
docker push myname/api:latest

docker push 흐름 — 레지스트리 로그인부터 푸시까지

push는 레지스트리 인증 → 태그 지정 → 레이어 업로드 순서로 진행된다. 이미 업로드된 레이어는 다이제스트가 같으면 재전송하지 않아 빠르다. private 레지스트리는 로그인이 필수다.

bash

# Docker Hub 로그인
docker login

# 빌드 및 태그
docker build -t myteam/api:1.2.3 .
docker image tag myteam/api:1.2.3 myteam/api:latest

# 둘 다 push
docker push myteam/api:1.2.3
docker push myteam/api:latest

시맨틱 버저닝 태그 전략

안정적인 배포를 위해 1.2.3(패치), 1.2(마이너), 1(메이저), latest를 모두 유지하는 전략을 쓴다. CI에서는 커밋 SHA나 빌드 날짜를 태그로 추가해 재현성을 확보한다.

bash

VERSION=1.2.3
docker build -t myteam/api:${VERSION} .
docker image tag myteam/api:${VERSION} myteam/api:1.2
docker image tag myteam/api:${VERSION} myteam/api:1
docker image tag myteam/api:${VERSION} myteam/api:latest

docker push myteam/api:${VERSION}
docker push myteam/api:1.2
docker push myteam/api:1
docker push myteam/api:latest

태그와 다이제스트는 "편의 이름"과 "실제 식별자"로 나눠서 봐야 한다

운영 문맥에서 재현성이 중요하면 다이제스트가 진짜 기준이고, 태그는 사람이 다루기 쉬운 별칭입니다. 개발과 릴리스 관리에는 태그가 편하지만, 배포 고정과 롤백 근거는 다이제스트가 더 안전합니다.

체크포인트

상황	적합한 선택
배포 이력 추적이 필요할 때	시맨틱 버전(`1.2.3`) 또는 커밋 SHA 태그
CI 빌드 재현성 보장	날짜 또는 SHA 기반 태그 추가
정확한 버전 고정이 중요할 때	태그 대신 다이제스트(`@sha256:...`)로 pull
latest만 사용하는 경우	팀 환경에서는 피해야 함

주의할 점

latest 태그만 운영하면 어느 시점의 이미지가 배포됐는지 추적할 수 없다. 장애 발생 시 롤백 대상을 특정하려면 반드시 재현 가능한 태그(버전, 커밋 SHA, 빌드 날짜)를 하나 이상 함께 유지해야 한다.

bash

docker pull myteam/api:latest

# 어제와 오늘의 latest가 같은 보장을 할 수 없어
# 장애 재현과 롤백 대상을 특정하기 어려움

참고 링크

2 sources

Reference

Opening reference

Preparing the article, table of contents, and metadata. 본문, 목차, 메타데이터를 준비하고 있습니다.

Docker이미지와 빌드

image tag와 push

이미지 이름과 태그가 버전 식별과 배포 경로를 결정한다는 점을 중심으로 build, tag, push 흐름을 정리합니다.

마지막 수정 2026년 4월 2일

빠른 흐름

bash

docker build -t myname/my-app:1.2.3 .
docker push myname/my-app:1.2.3

기본 흐름

어떤 태그와 배포 기준을 먼저 떠올리면 되나

상황	먼저 떠올릴 선택
재현 가능한 배포 버전 필요	시맨틱 버전 또는 SHA 태그
정확한 이미지 고정이 중요	다이제스트 pull
편의용 최신 별칭 유지	`latest`는 보조 태그로만 사용
레지스트리 업로드	`docker login` → `build/tag/push`

태그가 이미지 다이제스트(SHA256)에 대한 가변 포인터인 이유

bash

# 다이제스트로 정확한 버전을 고정해서 pull
docker pull myname/my-app@sha256:abc123...

# 이미지의 실제 다이제스트 확인
docker inspect --format='{{index .RepoDigests 0}}' myname/my-app:1.2.3

latest 태그의 위험성과 재현 불가능한 빌드

bash

# latest만 push하면 어떤 빌드인지 추적 불가
docker push myname/api:latest  # 피해야 할 패턴

# 명시적 버전 + latest를 함께 push (latest는 편의용 별칭)
docker push myname/api:1.2.3
docker push myname/api:latest

docker push 흐름 — 레지스트리 로그인부터 푸시까지

bash

# Docker Hub 로그인
docker login

# 빌드 및 태그
docker build -t myteam/api:1.2.3 .
docker image tag myteam/api:1.2.3 myteam/api:latest

# 둘 다 push
docker push myteam/api:1.2.3
docker push myteam/api:latest

시맨틱 버저닝 태그 전략

bash

VERSION=1.2.3
docker build -t myteam/api:${VERSION} .
docker image tag myteam/api:${VERSION} myteam/api:1.2
docker image tag myteam/api:${VERSION} myteam/api:1
docker image tag myteam/api:${VERSION} myteam/api:latest

docker push myteam/api:${VERSION}
docker push myteam/api:1.2
docker push myteam/api:1
docker push myteam/api:latest

태그와 다이제스트는 "편의 이름"과 "실제 식별자"로 나눠서 봐야 한다

체크포인트

상황	적합한 선택
배포 이력 추적이 필요할 때	시맨틱 버전(`1.2.3`) 또는 커밋 SHA 태그
CI 빌드 재현성 보장	날짜 또는 SHA 기반 태그 추가
정확한 버전 고정이 중요할 때	태그 대신 다이제스트(`@sha256:...`)로 pull
latest만 사용하는 경우	팀 환경에서는 피해야 함

주의할 점

bash

docker pull myteam/api:latest

# 어제와 오늘의 latest가 같은 보장을 할 수 없어
# 장애 재현과 롤백 대상을 특정하기 어려움

참고 링크

2 sources