이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- 배포 전 설정 체크리스트는 어떤 설정 사고를 막기 위한 문서인가?
- Spring profile, Secret, DB URL, Actuator, migration, rollback 조건을 어떻게 점검해야 하는가?
- 체크리스트가 형식 문서가 아니라 실제 운영 판단 도구가 되려면 무엇이 필요한가?
개요
배포 전 설정 체크리스트는 배포 직전 “정말 이 artifact가 이 설정으로 운영에 올라가도 되는가”를 확인하는 문서다.
체크리스트는 길수록 좋은 것이 아니다.
장애로 이어지는 설정 차이를 배포 전에 잡고, 실패하면 어디서 멈출지 정하는 것이 목적이다.
Spring 백엔드에서는 profile, datasource, Secret, external API, actuator, port, migration, rollback 조건을 반드시 확인해야 한다.
체크리스트의 기준
좋은 체크리스트는 세 가지를 가진다.
- 확인 항목
- 기대값
- 실패 시 행동
나쁜 체크리스트는 “설정 확인”처럼 추상적이다.
좋은 체크리스트는 “prod profile active, DB_URL은 prod writer endpoint, actuator env 미노출, image digest는 release note와 일치”처럼 판단 가능하다.
배포 전 기본 정보
먼저 release 정보를 고정한다.
service: order-api
environment: prod
release: 2026.06.30-3f21a9c
artifact_digest: sha256:...
profile: prod
config_source: /etc/order-api/order-api.env
secret_version: order-api-prod-v12
migration: V42 additive index
rollback_target: 2026.06.29-a819e00이 정보 없이 체크리스트를 실행하면 무엇을 검증했는지 나중에 알기 어렵다.
Profile 점검
Spring profile은 배포 전후 모두 확인한다.
grep SPRING_PROFILES_ACTIVE /etc/order-api/order-api.env
journalctl -u order-api --since "5 minutes ago" | grep 'profile'확인할 항목:
- prod 배포에서
prodprofile이 활성화되는가? - local/dev profile이 같이 켜져 있지 않은가?
- profile별 datasource와 external API endpoint가 맞는가?
- actuator exposure가 prod 기준으로 제한되어 있는가?
실패 시에는 배포를 멈추고 environment source를 확인한다.
profile이 틀린 상태로 트래픽을 열면 외부 시스템 오호출이나 데이터 오염이 생길 수 있다.
Config와 Secret 점검
Config와 Secret은 key 존재 여부와 source를 확인한다.
Secret 값 자체를 체크리스트에 쓰지 않는다.
DB_URL: present, prod writer endpoint
DB_USERNAME: present
DB_PASSWORD: secret manager order-api-prod-v12
PAYMENT_API_KEY: secret manager payment-prod-v7확인할 항목:
- 필요한 key가 모두 있는가?
- Secret 값이 Git, image, CI log에 노출되지 않았는가?
- Secret version이 release note와 일치하는가?
- 회전 직후라면 이전 Secret 폐기 시점이 정해져 있는가?
실패 시에는 신규 배포를 멈추고 Secret 적용 범위를 확인한다.
DB와 Migration 점검
DB 설정은 profile보다 더 직접적인 장애를 만든다.
확인할 항목:
- DB URL이 prod writer인지 read replica인지 맞는가?
- connection pool size가 인스턴스 수와 DB max connections 안에 들어가는가?
- migration이 additive change인지 destructive change인지 구분했는가?
- 구버전과 신버전이 같은 schema에서 동시에 동작할 수 있는가?
- migration 실패 시 forward fix인지 rollback인지 정했는가?
DB migration이 포함되면 artifact rollback만으로 충분하지 않을 수 있다.
배포 전 이 판단을 적어야 장애 중 복구가 빨라진다.
Port, Actuator, Health 점검
운영에서 트래픽이 붙으려면 port와 health가 맞아야 한다.
server.port=8080
management.server.port=8081
health path=/actuator/health
nginx upstream=127.0.0.1:8080확인할 항목:
- Spring port와 Nginx/LB upstream이 일치하는가?
- readiness와 liveness 기준을 구분했는가?
- management endpoint가 외부에 과도하게 열리지 않았는가?
- health check가 DB 장애를 어떻게 반영하는지 알고 있는가?
실패 시에는 트래픽 전환을 멈추고 내부 health와 외부 health를 분리해 확인한다.
배포 후 검증 항목
체크리스트는 배포 전에서 끝나지 않는다.
배포 직후 확인할 지표가 있어야 한다.
/actuator/health- 핵심 API smoke test
- HTTP 5xx rate
- latency p95/p99
- application error log
- Hikari pool pending
- external API timeout
- Nginx 502/504
검증 창도 정한다.
작은 서비스라도 5~10분은 주요 지표를 본다.
이 시간이 없으면 배포 성공을 너무 빨리 선언하게 된다.
실패 시 중단 조건
체크리스트에는 중단 조건이 있어야 한다.
예시:
- active profile이 기대와 다르면 배포 중단
- Secret key 누락이면 배포 중단
- migration이 destructive인데 호환 계획이 없으면 배포 중단
- smoke test 실패면 traffic 전환 중단
- 5xx가 기준선의 2배 이상이면 rollback 검토
- DB pool pending이 증가하면 batch와 재시도 정책 확인
중단 조건이 없으면 체크리스트는 확인표가 아니라 의식 절차가 된다.
인프라 담당자와 공유할 자료
배포 전 확인 결과:
- artifact digest 일치
- SPRING_PROFILES_ACTIVE=prod
- DB_URL=prod writer endpoint
- Secret version=order-api-prod-v12
- Nginx upstream=127.0.0.1:8080
- migration=V42 additive, rollback 호환
요청:
- LB target health 전환 시점 확인
- 배포 후 10분간 5xx와 p95 공동 관찰이 정보는 인프라 담당자가 트래픽 전환과 런타임 설정을 같이 확인하게 만든다.
실전 팁
- 체크리스트는 서비스별로 다르게 만든다.
- key 이름, 기대값, source, 실패 시 행동을 한 줄에 둔다.
- Secret 값은 쓰지 말고 version과 source만 쓴다.
- 배포 전 체크와 배포 후 검증을 같은 문서에 둔다.
- 마지막 장애에서 놓친 항목을 체크리스트에 추가한다.
위험 신호!
- 체크리스트가 “설정 확인” 같은 추상 문장으로만 되어 있다.
- 배포자가 현재 artifact digest를 모른다.
- Secret version과 config source를 확인하지 않는다.
- migration이 있는데 rollback 조건이 없다.
- health check만 성공하면 배포 성공으로 본다.
- 실패 시 중단 조건 없이 계속 진행한다.
확인 질문
확인 질문
- 배포 전 설정 체크리스트가 막으려는 핵심 사고는 무엇인가?
- 올바른 artifact가 잘못된 profile, Secret, DB URL, port, health 기준으로 운영에 올라가 장애를 만드는 사고다.
- 체크리스트에 기대값과 실패 시 행동이 필요한 이유는 무엇인가?
- 단순 확인 문구만 있으면 이상을 발견해도 배포를 멈출지, 수정할지, rollback할지 판단할 수 없기 때문이다.
- Secret 값 자체를 체크리스트에 쓰면 안 되는 이유는 무엇인가?
- 체크리스트가 공유되거나 로그로 남을 때 Secret이 노출될 수 있으므로 version, source, key 존재 여부만 기록해야 한다.