자동 배포 롤백 방법 없으면 새벽에 서비스가 죽습니다

새벽 서비스 롤백 대표 삽화

작성자

카테고리:

새벽에 알림이 울렸다. 자동 배포로 올라간 버전이 헬스체크에서 떨어졌다는 내용이다. 이때 자동 배포 롤백 방법을 미리 적어 두지 않았다면, 잠이 완전히 깬 뒤에도 한참 동안 “뭘 되돌려야 하지?”부터 고민하게 된다.

나는 운영 중인 서비스를 자동 배포로 굴린다. 처음에는 코드만 이전 커밋으로 돌리면 끝인 줄 알았다.

롤백 대상은 네 가지로 나눠서 생각한다. 코드, 산출물, 설정, 데이터다. 코드는 저장소의 커밋이다. 산출물은 빌드 결과물인 이미지나 번들 파일이다. 설정은 환경변수, 시크릿, 피처 플래그 값이다. 데이터는 DB 스키마와 실제 레코드다. 코드만 이전 커밋으로 돌리면 산출물은 따라 바뀌지만, 설정과 데이터는 새 배포 때 값 그대로 남는다.

실제로 코드는 직전 릴리스로 돌아갔는데 환경변수는 새 키 이름 그대로였던 적이 있다. 구버전 코드는 옛 키를 찾다가 기본값으로 떨어졌고, 외부 콜백 주소가 엉뚱한 곳으로 나갔다. 롤백했는데 상황이 더 나빠진 느낌이었다. 그 뒤로는 릴리스 단위에 설정 파일 버전을 같이 묶는다.

되돌릴 수 없는 것도 따로 적어 둔다. 발송된 메일, 외부 결제 API로 이미 나간 호출, 웹훅으로 넘어간 이벤트는 배포를 되돌려도 취소되지 않는다. 메일은 다시 보낼 수 없고, 결제는 취소 호출을 따로 해야 한다. 그래서 배포 계획 문서 첫 줄에 “이 배포가 밖으로 내보내는 것”을 적는다.

자동 배포에서 롤백이 일어나는 흐름은 보통 이렇다. 헬스체크가 실패하면 파이프라인이 직전 릴리스 태그를 다시 배포하고 트래픽을 그쪽으로 넘긴다. 사람이 개입하는 경우는 자동 롤백이 멈췄거나, DB 변경처럼 자동으로 되돌리기 어려운 변경이 섞였을 때다.

언제 되돌릴지: 헬스체크, 에러율, 고객 문의를 어떻게 판단하나

되돌릴지 말지는 신호 세 개를 같이 본다. 헬스체크는 즉시성을, 에러율은 영향 범위를, 고객 문의는 체감을 알려준다. 하나만 보면 판단이 흔들린다. 헬스체크는 초록불인데 특정 결제 경로만 죽은 적도 있었고, 에러율은 높은데 문의는 한 건도 없던 적도 있었다.

신호 무엇을 보나 판단 기준을 세우는 방법
헬스체크 배포 직후 연속 실패 여부 몇 번 연속 실패하면 롤백할지 서비스마다 정한다
5xx 에러율 배포 전 기준선 대비 상승 폭, 영향받는 경로 배포 전 평소 평균을 기준선으로 잡고, 특정 경로에만 몰리는지 본다
고객 문의 같은 증상이 반복되는지 같은 증상의 문의가 연달아 들어오면 원인 확인을 시작한다

표에 임계치 숫자는 일부러 적지 않았다. 여기 숫자를 적으면 그대로 복사해 쓰는 사람이 생길 것 같아서다. 임계치는 서비스마다 직접 정해야 한다. 트래픽이 많은 서비스와 적은 서비스의 에러율은 의미가 다르다.

판단 시간창도 미리 정해 둔다. 배포 직후에는 헬스체크를 보고, 조금 지나서는 에러율을, 더 지나서는 문의를 본다. 시간창을 정하지 않으면 새벽에 조급해져서 몇 분 간격으로 판단이 뒤집힌다.

늦게 되돌린 쪽보다 너무 빨리 되돌린 쪽이 더 오래 남는다. 에러율이 튀어서 바로 롤백했는데, 원인은 배포가 아니라 외부 API의 일시 장애였다. 롤백은 괜히 한 셈이 됐고, 그 배포에 들어 있던 수정까지 같이 빠졌다. 그 뒤로는 에러가 특정 외부 연동 경로에만 몰리는지 먼저 본다.

원인은 모르는데 영향이 한 기능 안에 갇혀 있으면, 그 기능의 플래그만 끄고 배포는 그대로 둔다. 되돌리는 것도 변경이라서, 되돌린 뒤의 상태를 또 확인해야 한다.

이전 버전은 어디에 어떻게 보관해야 현실적인가

보관하지 않았을 때 생기는 일부터 말하면, 직전 커밋으로 돌리려는데 그 커밋의 빌드 결과물은 이미 정리돼서 없다. 다시 빌드하는 동안 의존성이 달라졌는지 확인하느라 시간을 더 쓴다. 롤백할 대상이 코드 해시만 있고 이미지가 없으면 롤백이 아니라 재빌드가 된다.

내가 쓰는 방식은 코드 해시와 빌드 산출물을 같이 태깅하는 것이다. 이미지 태그는 서비스명, 날짜, 짧은 해시 순서로 짓는다.

git tag -a rel-clipsquare-20261116-a1b2c3d -m "prod release" a1b2c3d

서버에 직접 올리는 서비스는 릴리스 디렉터리에 버전별로 풀고, current 심볼릭 링크만 바꾼다. 되돌릴 때는 링크를 직전 디렉터리로 돌리고 프로세스를 재시작한다. 전환 자체는 단순한데, 설정 파일이 같은 디렉터리 안에 있는지를 먼저 확인해야 한다. 나는 설정 파일 사본을 릴리스 디렉터리에 같이 두고, 시크릿은 값을 복사하지 않고 이름만 기록한다.

보관 개수는 디스크 여유와 정리 주기로 정한다. 작업 폴더가 서버에 41개, 노트북에 35개까지 쌓이고 나서야 정리 기준을 세웠다. 정리 스크립트가 최근 릴리스까지 지운 적이 있어서, 지우기 전에 태그 목록과 대조하도록 바꿨다. 보관 비용은 디스크 몇 기가 수준이지만, 정리 실수는 롤백 자체를 불가능하게 만든다.

새벽에 울리는 배포 알림

롤백 실행 절차: 동결, 재배포, 되돌린 뒤 확인

순서는 세 단계다. 플랫폼이 무엇이든 순서는 같다.

  1. 동결. 새 배포를 멈추고, 이 배포와 연결된 크론 잡과 큐 소비자를 일시정지한다. 크론이 서버에 70개, 노트북에 9개 돌고 있어서, 이 단계를 건너뛰면 롤백 도중에 잡이 또 돈다. 서버 쪽 워커 하나를 멈추는 예는 이렇다.
    sudo systemctl stop clipsquare-worker.timer
  2. 재배포. 직전 릴리스 태그와 그 시점의 설정 파일을 같이 배포하고 트래픽을 옮긴다. 여기서 “되돌렸다”의 완료 기준을 정한다. 헬스체크가 관찰 시간창 동안 계속 정상이고, 5xx 에러율이 배포 전 기준선으로 내려오고, 큐 적체가 줄어드는 추세이고, 같은 증상의 문의가 더 들어오지 않아야 완료다. 네 가지가 모두 맞아야 완료로 친다.
  3. 되돌린 뒤 확인. 헬스체크와 에러율 말고도 아래를 본다.
    • 큐: 롤백 중에 쌓인 작업이 구버전으로 처리되는지, 실패한 작업이 재시도 루프에 빠지지 않았는지
    • 캐시: 신버전이 만든 캐시 키가 구버전과 어긋나지 않는지, 필요하면 해당 키만 비운다
    • 외부 웹훅: 실패한 웹훅이 재전송 대기에 있는지, 재전송하면 중복 전송이 되는지
    • 크론: 동결했던 잡이 다시 켜졌을 때 한 번만 도는지

되돌린 뒤 크론이 두 번 돈 적이 있다. 동결 단계에서 노트북 쪽 잡을 빠뜨렸기 때문이다. 그 뒤로는 작업마다 멱등 키를 두고, 동결 대상 목록을 서버와 노트북 양쪽에서 같이 뽑아 대조한다. 큐에 남은 작업은 버리지 않고 구버전이 처리할 수 있는 것만 남기고, 나머지는 보류 목록으로 뺐다.

헬스체크와 에러율 모니터링 화면

DB 변경이 섞인 배포에서 롤백할 때 조심할 것

이 부분이 제일 까다롭다. DB는 롤백하지 않는다고 단정하기보다, 코드 롤백과 DB 변경을 분리해서 설계하는 쪽이 현실적이다. 구버전 코드가 신버전이 만든 DB를 읽을 수 있어야 코드 롤백이 성립하기 때문이다.

컬럼 이름을 바꾸거나 지우는 변경은 한 번의 배포로 끝내지 않는다. 확장-수축(expand-contract) 패턴으로 나눈다.

  1. 확장: 새 컬럼을 NULL 허용으로 추가한다. 구버전은 이 컬럼을 무시하고 돌아간다.
  2. 전환: 신버전은 두 컬럼에 함께 쓰고, 읽기는 새 컬럼을 우선한다. 구버전과 신버전이 같이 도는 기간이 바로 이 구간이다.
  3. 수축: 충분히 지난 뒤 다음 배포에서 옛 컬럼을 지운다.
ALTER TABLE orders ADD COLUMN status_v2 VARCHAR(20) NULL;

되돌릴 수 없는 변경인지는 아래 표로 거른다.

변경 종류 되돌릴 수 있나 이유
NULL 허용 컬럼 추가 가능 구버전이 무시한다
컬럼 삭제 불가 데이터가 사라진다. 백업에서만 복구된다
값 변환을 UPDATE로 일괄 적용 어렵다 원래 값을 따로 남기지 않으면 역변환이 안 된다
열거형 값 추가 주의 구버전이 모르는 값을 읽다 에러가 난다

코드만 되돌렸더니 신버전이 저장한 새 상태값을 구버전이 모르는 값으로 읽어서 에러가 난 적이 있다. 그 뒤로 규칙을 두 개 정했다. 마이그레이션은 되돌리지 않고 앞으로만 간다. 스키마 배포와 코드 전환 배포는 따로 낸다. 롤백 전에는 구버전 파서가 못 읽는 값이 DB에 있는지 쿼리로 한 번 확인한다.

롤백 자체가 실패하지 않도록 미리 점검할 것

롤백 스크립트는 배포 스크립트만큼 자주 돌지 않아서 조용히 깨진다. 이미지 레지스트리 주소가 바뀌었는데 롤백 스크립트에는 옛 주소가 남아 있었다. 막상 써야 할 때 이미지를 찾을 수 없다는 에러가 떴다. 배포는 매번 돌아서 그동안은 몰랐던 것이다.

그래서 롤백도 배포처럼 테스트한다. 스테이징에서 직전 릴리스로 실제로 되돌려 보고 헬스체크가 통과하는지 확인한다. 주기는 정해서 달력에 적어 둔다. 주기를 적어 두지 않으면 나중에 하면 된다가 된다.

리허설 체크리스트는 이렇다.

  • 직전 릴리스 태그가 레지스트리에 실제로 있는가
  • 롤백 스크립트의 주소, 경로, 환경변수 이름이 지금과 맞는가
  • 배포 계정 권한이 살아 있고 시크릿이 만료되지 않았는가
  • 의존 서비스 DB, 결제, 메일이 지금 정상 응답하는가
  • 동결 대상 크론 목록이 최신인가
이전 버전 보관 선반과 되감기

요약: 한 장짜리 롤백 런북

런북은 한 장이면 충분하다. 실제로 쓰는 런북은 아래 네 줄로 시작한다. 처음 만들 때는 맨 위의 “되돌릴 수 없는 것” 항목이 빠져 있었다. 메일을 보낸 뒤에야 떠올랐다.

  1. 되돌릴 것: 코드, 산출물, 설정 버전, DB 변경 여부
  2. 되돌릴 조건: 신호별 판단 기준과 관찰 시간창
  3. 동결 대상: 크론 목록, 큐 소비자, 외부 발송 경로
  4. 완료 기준: 헬스체크, 에러율, 큐, 캐시, 웹훅, 문의

DB 변경이 있는 배포도 자동 롤백에 맡겨도 되나요?

코드만 바뀐 배포라면 자동 롤백에 맡겨도 된다. DB 변경이 섞였다면 자동으로 되돌리지 말고, 사람이 먼저 구버전과 신버전의 호환성을 본다.

롤백한 뒤 원인을 고쳐서 바로 다시 배포해도 되나요?

문제를 재현해서 스테이징에서 확인한 뒤에 배포한다. 다시 배포하고 나서도 관찰 시간창은 처음부터 똑같이 지킨다.


글쓴이 정보

춘천에서 AI 자동화로 서비스를 만들어 운영합니다. 릴스·쇼츠는 직접 만든 ClipSquare 로 만듭니다.

궁금해할 만한 것들

자동 배포 롤백은 코드만 이전 커밋으로 되돌리면 되나요?

코드만 되돌리면 빌드 산출물은 따라 바뀌지만, 환경변수·시크릿·피처 플래그 같은 설정과 DB 데이터는 새 배포 값 그대로 남는다. 구버전 코드가 새 키 이름을 모르면 기본값으로 떨어져서 롤백한 뒤에 오히려 상황이 나빠질 수 있다. 그래서 나는 릴리스 단위로 설정 파일 버전을 같이 묶어 둔다.

헬스체크가 통과하면 롤백하지 않아도 되나요?

헬스체크는 즉시성만 알려준다. 헬스체크는 초록불인데 특정 결제 경로만 죽어 있던 적이 있어서, 나는 5xx 에러율을 배포 전 기준선과 비교하고 같은 증상의 고객 문의가 반복되는지도 함께 본다. 임계치 숫자는 서비스 트래픽에 따라 직접 정해야 한다.

이미 발송된 메일이나 결제 호출도 배포를 되돌리면 취소되나요?

취소되지 않는다. 발송된 메일, 외부 결제 API로 나간 호출, 웹훅으로 넘어간 이벤트는 배포 롤백과 무관하게 그대로 남는다. 결제는 취소 호출을 따로 해야 하고 메일은 다시 보낼 수 없어서, 나는 배포 계획 문서 첫 줄에 이 배포가 밖으로 내보내는 것을 적어 둔다.