이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- 배포 전후 검증 체크리스트는 왜 단순 TODO 목록이 아니어야 하는가?
- 배포 전, 배포 중, 배포 후에 각각 어떤 증거를 확인해야 하는가?
- 체크리스트에 중단 조건과 rollback 기준을 어떻게 넣어야 하는가?
개요
배포 전후 검증 체크리스트는 배포자가 기억에 의존하지 않게 만드는 운영 문서다.
좋은 체크리스트는 “확인한다”로 끝나지 않는다.
확인 명령, 기대 결과, 실패 시 행동, 담당자, 중단 조건을 포함한다.
Spring 백엔드 배포에서는 artifact, config, DB migration, health, smoke test, metric, log, rollback target을 함께 본다.
체크리스트 헤더
체크리스트 첫 부분에는 배포 단위를 고정한다.
service: order-api
environment: production
version: 1.8.3-abc1234
strategy: rolling
deploy window: 2026-07-01 15:00 KST
operator: platform-oncall
application owner: order-team
rollback target: 1.8.2-ff9012
DB migration: V52 nullable column add이 정보가 없으면 장애 중 어떤 배포를 말하는지부터 헷갈린다.
배포 전 검증
배포 전에는 입력이 맞는지 확인한다.
[ ] artifact digest가 release note와 일치한다.
[ ] staging smoke test가 같은 artifact로 성공했다.
[ ] production config와 Secret version 변경이 승인되었다.
[ ] DB migration이 backward compatible로 리뷰되었다.
[ ] rollback target과 traffic 전환 방법이 준비되어 있다.배포 전 검증은 배포를 시작해도 되는지 결정하는 gate다.
실패한 항목이 있으면 배포를 미루는 것이 정상적인 선택이다.
배포 중 검증
배포 중에는 현재 진행률과 중단 조건을 본다.
[ ] readiness UP
[ ] 핵심 API smoke test 성공
[ ] error rate <= baseline + 0.2%
[ ] latency p95 <= baseline + 100ms
[ ] critical log pattern 없음
[ ] DB connection pool saturation 없음Rolling이면 batch마다 확인한다.
Blue-Green이면 traffic switch 전후를 나눠 확인한다.
Canary이면 비율을 올리기 전마다 확인한다.
배포 후 검증
배포 후에는 job 성공이 아니라 운영 안정성을 본다.
curl -fsS https://api.example.com/actuator/health/readiness
curl -fsS https://api.example.com/actuator/info
./smoke-test.sh --base-url https://api.example.com --suite core
./observe-window.sh --minutes 30 --watch error-rate,latency-p95,order-success-rate/actuator/info로 실행 중인 version이 기대 artifact인지 확인한다.
Metric과 log는 배포 전 baseline과 비교해야 한다.
중단 조건
체크리스트에는 중단 조건이 있어야 한다.
다음 중 하나라도 발생하면 배포 중단:
- readiness DOWN 3분 이상
- 5xx error rate baseline 대비 +0.5% 초과
- p95 latency baseline 대비 +200ms 초과
- order-create smoke test 실패
- DB migration lock wait 증가중단 조건이 없으면 장애 중에도 “조금 더 지켜보자”로 시간이 흐른다.
중단은 실패가 아니라 실패 반경을 줄이는 정상 절차다.
Rollback 기준
Rollback 기준은 배포 전에 준비한다.
rollback 가능:
- DB migration backward compatible
- previous artifact available
- traffic switch back tested
rollback 보류:
- destructive DB migration applied
- new data format not readable by previous version
- restore decision requiredRollback이 불가능한 경우에는 forward fix, feature flag off, read-only mode 같은 대안을 적어야 한다.
운영 체크리스트
- 배포 대상 service, version, strategy, 담당자가 적혀 있는가?
- artifact digest와
/actuator/info확인이 포함되어 있는가? - DB migration 호환성 검토가 포함되어 있는가?
- 배포 전략별 중단 조건이 수치로 적혀 있는가?
- 배포 후 관측 시간이 정해져 있는가?
- rollback target과 불가능 조건이 함께 적혀 있는가?
- 체크리스트 실행 결과를 장애 회고에 재사용할 수 있는가?
장애 신호
- 체크리스트가 있지만 기대값이 없어 통과 여부가 사람마다 다르다.
- 배포 후 어떤 지표를 몇 분 볼지 정해져 있지 않다.
- smoke test는 성공했지만 business metric은 보지 않는다.
- rollback target이 비어 있거나
latest로 되어 있다. - DB migration 포함 여부가 체크리스트에 없다.
- 장애 후 체크리스트가 업데이트되지 않는다.
안전한 완화 조치
체크리스트 중 핵심 gate가 실패하면 배포를 멈춘다.
이미 배포가 일부 진행됐다면 현재 진행률, version, traffic 상태를 기록한다.
중단 조건을 넘은 상태에서 새 배포를 덮어쓰지 않는다.
Rollback 가능성이 있으면 artifact와 DB 호환성을 확인하고 실행한다.
Rollback이 위험하면 feature flag off나 traffic reduction으로 시간을 확보한다.
인프라 담당자와 공유할 자료
배포 체크리스트 실행 결과
service: order-api
version: 1.8.3-abc1234
strategy: canary 5%
failed gate: p95 latency baseline +250ms
smoke test: order-create success
DB migration: V52 backward compatible
current action: canary 5% 유지, 25% 전환 중단
요청: DB query latency와 connection pool 지표 확인체크리스트 결과는 장애 중 공통 사실 테이블로 쓰인다.
실전 팁
- 체크리스트는 명령, 기대값, 실패 시 행동을 한 줄에 둔다.
- 배포 전략별로 확인 주기를 다르게 둔다.
- version과 DB migration 정보를 반드시 헤더에 넣는다.
- smoke test와 metric을 둘 다 본다.
- 마지막 배포 실패에서 빠졌던 항목을 다음 체크리스트에 반영한다.
위험 신호!
- 체크리스트가 “확인 완료” 같은 추상 문장만 있다.
- 중단 조건이 수치가 아니라 감각으로 적혀 있다.
- rollback 가능 여부를 배포 후에 처음 검토한다.
- 실패한 gate가 있는데 다음 단계로 진행한다.
- 장애 회고에서 체크리스트 실행 결과를 찾을 수 없다.
확인 질문
확인 질문
- 좋은 배포 체크리스트가 TODO 목록과 다른 점은 무엇인가?
- 확인 명령, 기대 결과, 실패 시 행동, 담당자, 중단 조건을 포함해 실제 판단을 가능하게 만든다는 점이다.
- 배포 후 검증에서
/actuator/info가 필요한 이유는 무엇인가?
- 실제 실행 중인 version과 기대 artifact가 같은지 확인해야 잘못된 version 배포를 빠르게 잡을 수 있기 때문이다.
- 중단 조건을 사전에 적어야 하는 이유는 무엇인가?
- 장애 중 즉흥 판단을 줄이고 지표가 기준을 넘었을 때 배포를 멈추는 결정을 빠르게 하기 위해서다.