VERSION=1.2.3
IMAGE=registry.example.com/team/my-app

docker build -t "${IMAGE}:${VERSION}" .
docker image tag "${IMAGE}:${VERSION}" "${IMAGE}:1.2"
docker push "${IMAGE}:${VERSION}"
docker push "${IMAGE}:1.2"

이미지 참조와 tag

tag는 registry 위치와 사람이 읽는 식별자를 함께 담는다

이미지 참조는 [HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG] 형태입니다. host를 생략하면 Docker Hub, tag를 생략하면 latest가 기본으로 적용됩니다. 이 기본값은 편의 문법일 뿐 registry 위치나 버전 정책을 대신 정해 주지 않습니다.

registry.example.com:5000/team/api:1.2.3
\______________________________/ \___/
      registry와 repository       tag

private registry로 push하려면 target name에 registry hostname과 필요한 port를 넣어야 합니다. docker image tag는 source image ID나 기존 name:tag를 받아 target name을 추가합니다.

tag가 image digest에 대한 가변 이름인 이유

image의 실제 배포 내용을 고정하는 식별자는 content-addressed digest입니다. tag는 그 digest에 붙이는 사람이 읽기 쉬운 별칭이므로, 같은 my-app:1.0.0을 두 번 pull해도 registry가 tag를 재지정했다면 서로 다른 image를 받을 수 있습니다.

# digest로 정확한 버전을 고정해서 pull
docker image pull myname/my-app@sha256:<digest>

# registry에서 pull한 image의 digest 확인
docker image inspect --format='{{json .RepoDigests}}' myname/my-app:1.2.3

로컬에서만 build했거나 archive를 load한 image는 RepoDigests가 비어 있을 수 있습니다. 정확한 배포 내용을 기록할 때는 push 출력 또는 registry 조회에서 받은 digest를 기록합니다.

publish 흐름

latest는 기본값이지 운영 정책이 아니다

latest는 Docker가 자동으로 관리하는 특별한 tag가 아닙니다. tag를 생략할 때 적용되는 기본값일 뿐이며, 어떤 image가 latest인지는 registry의 push 정책에 달려 있습니다. 팀에서 latest만 사용하면 어떤 코드가 배포됐는지 추적하기 어렵습니다.

# release tag와 편의용 alias를 따로 push
docker push myname/api:1.2.3
docker push myname/api:latest

push 전에 대상 registry와 권한을 확인한다

push는 registry 인증 → target tag 지정 → 레이어와 manifest 업로드 순서로 진행됩니다. private registry는 권한이 있어야 하며, 이미 registry에 있는 동일 내용의 layer는 다시 전송하지 않을 수 있습니다.

docker login registry.example.com
docker build -t registry.example.com/team/api:1.2.3 .
docker image tag registry.example.com/team/api:1.2.3 registry.example.com/team/api:latest
docker push registry.example.com/team/api:1.2.3
docker push registry.example.com/team/api:latest

배포 기록

안정적인 배포에서는 불변으로 취급할 1.2.3 또는 commit SHA tag를 기준으로 삼고, 1.2, 1, latest 같은 이동 가능한 alias는 정책을 정해 함께 갱신합니다. 날짜 tag만으로는 같은 날짜의 두 build를 구분하지 못할 수 있으므로, CI 식별자나 commit SHA를 보조로 둡니다.

VERSION=1.2.3
SHA=9f3a7c1
IMAGE=registry.example.com/team/api

docker build -t "${IMAGE}:${VERSION}" .
docker image tag "${IMAGE}:${VERSION}" "${IMAGE}:${SHA}"
docker push "${IMAGE}:${VERSION}"
docker push "${IMAGE}:${SHA}"

tag는 릴리스 탐색과 운영 명령에 편하지만, 배포 고정과 롤백 근거는 digest가 더 강합니다. 배포 기록에는 source commit, 사람이 읽는 release tag, push 결과의 digest, 대상 플랫폼을 함께 남깁니다. digest로 base image를 고정하는 기준은 image digest와 tag pinning 카드에서 다룹니다.