이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- Build artifact와 release는 무엇이 다르고 왜 분리해서 봐야 하는가?
- Spring Boot jar 또는 Docker image가 운영에서 추적 가능한 artifact가 되려면 무엇이 필요한가?
- 배포 장애 중 artifact 문제와 설정 문제를 어떻게 구분하는가?
개요
Build artifact는 소스 코드를 실행 가능한 결과물로 만든 것이다.
Spring Boot에서는 보통 bootJar로 만든 jar 파일이나 Docker image가 artifact다.
Release는 artifact에 운영 의미를 붙인 단위다.
같은 jar라도 어떤 profile, 환경 변수, Secret, DB migration, 배포 시간, 검증 결과와 묶였는지에 따라 운영에서 전혀 다른 release가 된다.
Artifact가 해결하는 문제
Artifact의 목적은 “지금 운영에서 무엇이 실행 중인가”를 설명할 수 있게 하는 것이다.
개발자가 서버에 접속해 임의로 다시 빌드하면 같은 source라고 해도 Gradle cache, dependency version, JDK version, local file 때문에 결과가 달라질 수 있다.
운영 artifact는 CI에서 만들고, registry나 artifact storage에 저장하고, version과 checksum으로 추적하는 편이 안전하다.
./gradlew clean test bootJar
sha256sum build/libs/order-api.jar
docker build -t registry.example.com/order-api:2026.06.30-3f21a9c .
docker inspect --format='{{index .RepoDigests 0}}' registry.example.com/order-api:2026.06.30-3f21a9ctag만으로 부족할 때는 image digest까지 남긴다.
tag는 재사용될 수 있지만 digest는 image content를 가리킨다.
Release 단위
Release note에는 artifact만 적으면 부족하다.
운영에서 필요한 release 단위는 다음을 포함한다.
- service name
- environment
- Git SHA
- artifact tag 또는 jar checksum
- image digest
- active profile
- config source
- Secret reference
- DB migration 포함 여부
- 배포 전후 검증 항목
- rollback 대상
service: order-api
environment: prod
git_sha: 3f21a9c
artifact: registry.example.com/order-api:2026.06.30-3f21a9c
image_digest: sha256:...
profile: prod
config: /etc/order-api/order-api.env
migration: V42 additive index only
verify: health, order-list smoke test, 5xx rate, p95 latency
rollback: 2026.06.29-a819e00이 정보가 있어야 장애 중 “최근 배포”를 구체적으로 말할 수 있다.
Spring Boot jar와 Docker image
jar 배포는 단순하고 디버깅이 쉽다.
하지만 서버의 JDK, 실행 사용자, 파일 권한, 환경 파일이 운영 결과에 큰 영향을 준다.
Docker image 배포는 JDK와 filesystem을 image에 고정할 수 있다.
하지만 image tag, base image, environment injection, volume, port mapping을 별도로 관리해야 한다.
어느 방식을 쓰든 artifact 안에 prod Secret을 넣으면 안 된다.
artifact는 환경 독립적으로 만들고, 환경별 값은 배포 시 주입한다.
장애 중 구분 방법
배포 직후 장애가 났을 때 먼저 묻는다.
- 이전 release와 artifact가 다른가?
- artifact는 같고 config만 달라졌는가?
- image tag는 같지만 digest가 달라졌는가?
- active profile이 예상과 같은가?
- migration이 포함되어 이전 artifact로 rollback 가능한가?
- 같은 release가 일부 인스턴스에서만 실패하는가?
artifact가 잘못되면 모든 환경에서 같은 방식으로 실패할 가능성이 크다.
config가 잘못되면 특정 환경이나 특정 인스턴스에서만 실패할 수 있다.
운영 체크리스트
- CI가 artifact를 한 번만 만들고 그 결과물을 promotion하는가?
- artifact version이 Git SHA와 연결되는가?
- Docker tag 재사용을 금지하는가?
- image digest나 jar checksum을 release note에 남기는가?
- artifact 안에 운영 Secret이 포함되지 않는가?
- release note에 profile과 config source가 포함되는가?
- rollback 대상 artifact가 registry나 storage에 남아 있는가?
장애 신호
- 운영 서버에서 실행 중인 jar가 어떤 commit인지 모른다.
latesttag만 사용해 rollback 대상이 불분명하다.- 같은 tag를 다시 push해 서버마다 다른 image를 실행한다.
- 배포 후 smoke test 없이 pipeline이 성공으로 끝난다.
- rollback하려는데 이전 artifact가 삭제되어 없다.
- artifact는 이전과 같은데 특정 서버만 DB URL이 다르다.
안전한 완화 조치
artifact 문제가 의심되면 신규 배포를 멈추고 현재 실행 중인 version을 고정한다.
이전 artifact가 있고 DB 변경이 호환된다면 rollback을 검토한다.
DB migration이나 데이터 변경이 포함된 release는 artifact만 되돌려도 해결되지 않을 수 있다.
이때는 forward fix, feature flag off, traffic shift, read-only mode 중 무엇이 안전한지 본다.
tag 재사용이 의심되면 digest 기준으로 어떤 image가 배포되었는지 확인한다.
인프라 담당자와 공유할 자료
서비스: order-api prod
문제 release: 2026.06.30-3f21a9c
image: registry.example.com/order-api:2026.06.30-3f21a9c
digest: sha256:...
이전 release: 2026.06.29-a819e00
변경: order list pagination, DB migration V42 포함
증상: 배포 후 /api/orders p95 240ms -> 3.1s
확인 요청: 인스턴스별 image digest와 active profile 일치 여부인프라 담당자는 registry, 배포 도구, 서버별 실행 상태를 확인할 수 있고, 백엔드는 release 의미와 DB 호환성을 설명해야 한다.
실전 팁
- build와 deploy를 같은 서버에서 즉흥적으로 하지 않는다.
- artifact tag에는 날짜보다 Git SHA나 build number를 함께 넣는다.
- rollback 문서에는 이전 artifact와 config compatibility를 같이 적는다.
- release note는 장애 회고의 첫 번째 증거가 된다.
- jar 배포든 Docker 배포든 “무엇이 실행 중인가”를 명령으로 확인할 수 있게 한다.
위험 신호!
- 운영에서 직접
./gradlew bootJar를 실행해 배포한다. - Docker image tag를 재사용한다.
- release note에 config와 migration 정보가 없다.
- artifact와 source commit을 연결할 방법이 없다.
- rollback 대상 artifact 보관 기간이 정해져 있지 않다.
확인 질문
확인 질문
- Build artifact와 release의 차이는 무엇인가?
- artifact는 실행 가능한 결과물이고, release는 그 artifact를 특정 환경 설정, 검증, migration, rollback 조건과 묶은 운영 단위다.
- image digest를 남기는 이유는 무엇인가?
- tag가 재사용되거나 서버마다 다른 image를 가져간 경우에도 실제 실행 content를 추적하기 위해서다.
- artifact rollback 전에 확인해야 할 것은 무엇인가?
- DB migration과 데이터 변경이 이전 artifact와 호환되는지, 이전 artifact가 보관되어 있는지, config도 함께 되돌려야 하는지다.