동블

그래프 뷰

03. Artifact Version Tagging 상세

7 min read

이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.

  • Artifact version과 tag는 운영 배포에서 왜 필요한가?
  • latest tag만 쓰면 rollback과 장애 분석에서 어떤 문제가 생기는가?
  • git SHA, release tag, image digest, checksum을 어떻게 연결해야 하는가?

개요

Artifact Version Tagging은 배포된 산출물을 추적 가능한 단위로 만드는 작업이다.

운영 장애가 났을 때 가장 먼저 묻는 것 중 하나는 “지금 어떤 버전이 떠 있는가”다.

이 질문에 답하지 못하면 rollback 대상도, 원인 commit도, 재현할 artifact도 찾기 어렵다.

버전은 사람을 위한 이름이면서 동시에 pipeline과 운영 시스템이 읽는 증거다.

Artifact의 종류

Spring 백엔드에서 artifact는 여러 형태가 될 수 있다.

Jar 파일, Docker image, release note, deploy script input이 모두 artifact 추적의 대상이 될 수 있다.

pipeline은 이 artifact들이 같은 git commit에서 나왔는지 연결해야 한다.

Jar는 order-api-1.4.2+abc1234.jar처럼 이름을 가질 수 있다.

Docker image는 registry.example.com/order-api:1.4.2-abc1234처럼 tag를 가질 수 있다.

하지만 tag는 움직일 수 있으므로 digest까지 남기는 것이 더 정확하다.

Tag 전략

latest만 쓰면 운영에 어떤 코드가 올라갔는지 알 수 없다.

권장되는 tag는 목적별로 나눌 수 있다.

git sha tag: registry.example.com/order-api:abc1234
release tag: registry.example.com/order-api:1.4.2
build tag: registry.example.com/order-api:20260701.1530.1821
digest: registry.example.com/order-api@sha256:...

git SHA는 정확한 code input을 가리킨다.

release tag는 사람과 changelog가 읽기 쉽다.

build tag는 pipeline run과 연결하기 좋다.

digest는 실제 image content를 고정한다.

Pipeline 예시

env:
  IMAGE: registry.example.com/order-api
  VERSION: ${{ github.ref_name }}-${{ github.sha }}
 
steps:
  - uses: actions/checkout@v4
  - run: ./gradlew clean test bootJar
  - run: docker build -t $IMAGE:${{ github.sha }} .
  - run: docker push $IMAGE:${{ github.sha }}
  - id: digest
    run: |
      DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' $IMAGE:${{ github.sha }})
      echo "image_digest=$DIGEST" >> "$GITHUB_OUTPUT"

실제 pipeline에서는 push 이후 registry에서 digest를 조회해 release note에 남기는 편이 안전하다.

로컬 image inspect만으로는 registry가 최종적으로 가진 digest와 다를 수 있다.

배포 이력

배포 기록에는 최소한 다음 값이 있어야 한다.

  • service name
  • environment
  • git SHA
  • artifact version
  • image digest
  • pipeline run id
  • deploy time
  • deploy actor
  • migration 포함 여부
  • rollback target

이 값들이 없으면 장애 회고가 감으로 흐른다.

Spring Actuator 정보

Spring Boot Actuator의 info endpoint에 build 정보를 노출할 수 있다.

management.endpoints.web.exposure.include=health,info
management.info.git.mode=full

운영에서 /actuator/info를 볼 수 있다면 현재 실행 중인 commit과 build time을 확인할 수 있다.

단, 외부 공개 범위와 인증은 별도로 제한해야 한다.

운영 체크리스트

  • artifact 이름이나 image tag에 git SHA가 포함되는가?
  • release tag와 git tag가 연결되어 있는가?
  • image digest를 배포 기록에 남기는가?
  • CD가 CI에서 만든 artifact를 그대로 배포하는가?
  • latest tag에만 의존하지 않는가?
  • /actuator/info 또는 배포 metadata로 실행 버전을 확인할 수 있는가?
  • rollback target이 tag가 아니라 실제 digest나 artifact id로 고정되는가?

장애 신호

  • 운영 장애가 났는데 현재 실행 중인 commit을 모른다.
  • 같은 tag가 여러 번 push되어 rollback 대상이 바뀐다.
  • staging과 production이 같은 tag 이름인데 digest가 다르다.
  • pipeline run은 성공했지만 release note에 artifact id가 없다.
  • /actuator/info의 commit과 배포 기록의 commit이 다르다.
  • rollback이 latest 재배포로 수행된다.

안전한 완화 조치

버전 추적이 안 되는 상태에서 새 배포를 덮어쓰면 증거를 잃는다.

먼저 현재 실행 중인 artifact를 확인한다.

curl -fsS https://api.example.com/actuator/info
docker inspect registry.example.com/order-api:abc1234

tag 재사용이 의심되면 registry event와 digest history를 확인한다.

Rollback은 사람이 읽기 쉬운 tag보다 digest나 고정 artifact id를 기준으로 수행한다.

배포 기록이 부족했다면 다음 배포부터 pipeline output과 release note에 metadata를 강제한다.

인프라 담당자와 공유할 자료

증상: 배포 후 /api/orders 500 증가
service: order-api
environment: production
deployed image: order-api:1.4.2-abc1234
digest: sha256:9a...
pipeline run: 1821
previous stable: order-api:1.4.1-ff9012, sha256:31...
migration: V42 applied, backward compatible

장애 대응에서 version 정보는 로그와 metric을 같은 배포 단위로 묶는 기준이다.

실전 팁

  • latest는 편하지만 운영 추적 기준으로 쓰지 않는다.
  • tag와 digest를 같이 기록한다.
  • release note에는 사람이 읽는 버전과 기계가 읽는 digest를 같이 둔다.
  • Spring Actuator info로 runtime version을 확인할 수 있게 한다.
  • rollback 문서에는 “이전 정상 digest”를 명시한다.

위험 신호!

  • 같은 tag를 여러 번 push한다.
  • CD가 배포 시점에 새로 build한다.
  • 장애 회고에서 “아마 최신 버전”이라고 표현한다.
  • staging에서 검증한 artifact와 production artifact가 다르다.
  • rollback 대상이 latest다.

확인 질문

확인 질문

  • latest tag만 쓰면 왜 위험한가?
    • 같은 이름이 다른 artifact를 가리킬 수 있어 현재 운영 버전과 rollback 대상을 정확히 고정할 수 없기 때문이다.
  • image digest를 남겨야 하는 이유는 무엇인가?
    • tag가 움직여도 digest는 실제 image content를 고정하므로 재현과 rollback 증거가 된다.
  • Spring Actuator info가 배포 분석에 주는 장점은 무엇인가?
    • 실제 실행 중인 애플리케이션의 commit, build time, version을 endpoint로 확인해 배포 기록과 대조할 수 있다.

참고 문서

관련 문서

백링크