본문으로 건너뛰기

롤백

배포 후 문제가 발생했나요? 롤백을 사용하면 빠르게 이전 버전으로 복원할 수 있습니다. 새 버전에서 버그가 발견되었거나 성능 문제가 있을 때, 몇 번의 클릭만으로 안정된 이전 버전으로 돌아갈 수 있습니다.

롤백은 언제 필요한가요?
  • 새 버전 배포 후 예상치 못한 오류가 발생했을 때
  • 성능 저하나 메모리 누수가 발견되었을 때
  • 외부 서비스와의 호환성 문제가 발생했을 때
  • 사용자로부터 심각한 버그 리포트가 들어왔을 때

배포 관리 탭

롤백 개요​

런타임별로 롤백 방식이 다릅니다:

  • Kubernetes: Deployment 롤백 방식을 사용합니다. 이전 ReplicaSet으로 전환하며, 롤아웃 이력이 자동으로 관리됩니다.
  • Docker: 이전 이미지 재배포 방식을 사용합니다. 수동으로 이전 이미지 태그를 선택해야 합니다.

Kubernetes 롤백​

Kubernetes는 배포 이력을 자동으로 관리하여 간편하게 롤백할 수 있습니다.

Step 1: 배포 이력 확인​

  1. [서비스 관리] 페이지에서 서비스를 선택합니다 .
  2. Operate 단계를 클릭합니다 .
  3. K8s Deployment 탭을 선택합니다 .
  4. 롤아웃 이력 섹션에서 배포 기록을 확인합니다 .

롤아웃 이력 정보​

각 이력에서 다음 정보를 확인할 수 있습니다:

  • Revision: 배포 버전 번호 (최신이 가장 높음)
  • 이미지 태그: 해당 버전에 배포된 이미지
  • 배포 시간: 배포가 실행된 시점
  • 상태: 성공 / 실패
  • 변경 원인: 배포 트리거 (수동 / Auto CI / 롤백)

Step 2: 롤백할 버전 선택​

  1. 롤아웃 이력에서 복원하고 싶은 버전을 찾습니다 .
  2. 해당 버전의 롤백 버튼을 클릭합니다 .
어떤 버전으로 롤백해야 하나요?

일반적으로 직전 버전(현재 Revision - 1)으로 롤백합니다. 하지만 여러 버전에 걸쳐 문제가 있었다면 안정적으로 동작했던 더 이전 버전을 선택하세요.

Step 3: 롤백 확인​

  1. 확인 모달에서 롤백 대상 정보를 검토합니다:
    • 현재 버전
    • 롤백 대상 버전
    • 영향받는 Pod 수
  2. 롤백 실행 버튼을 클릭합니다 .
롤백 전 확인사항
  • DB 스키마가 변경되었다면 데이터 호환성 문제가 있을 수 있습니다 .
  • 환경 변수나 ConfigMap이 변경되었다면 이전 버전과 호환되는지 확인하세요

Step 4: 롤백 상태 모니터링​

[1/3] Initiating rollback to revision 5...
[2/3] Scaling down new pods...
   → Pod my-app-new-xxx: Terminating
[3/3] Scaling up old pods...
   → Pod my-app-old-xxx: Running (1/3)
   → Pod my-app-old-xxx: Running (2/3)
   → Pod my-app-old-xxx: Running (3/3)
Rollback completed successfully!

Step 5: 서비스 상태 확인​

롤백 완료 후 반드시 확인하세요:

  • 모든 Pod 상태가 Running인지
  • 서비스 응답이 정상인지 (Health Check 통과)
  • 로그에 오류가 없는지
  • 주요 기능이 정상 동작하는지

Docker 롤백​

Docker 환경에서는 이전 이미지 태그를 선택하여 재배포합니다.

Step 1: 이전 이미지 확인​

  1. [서비스 관리] 페이지에서 서비스를 선택합니다 .
  2. Operate 단계를 클릭합니다 .
  3. 배포 이력에서 이전 이미지 태그를 확인합니다 .
이미지 태그 찾기

빌드 이력에서 이전에 성공한 빌드의 이미지 태그를 확인할 수 있습니다. 태그 형식이 ${BRANCH}-${SHORT_SHA}라면 이전 커밋의 해시로 찾을 수 있습니다.

Step 2: 이전 버전 재배포​

  1. Deploy 단계를 클릭합니다 .
  2. 이미지 태그를 이전 버전으로 변경합니다 .
  3. 배포 버튼을 클릭합니다 .

Step 3: 컨테이너 상태 확인​

  1. Docker Containers 탭에서 상태를 확인합니다 .
  2. 새 컨테이너가 Running 상태인지 확인합니다 .
  3. 로그를 확인하여 오류가 없는지 검토합니다 .

긴급 롤백​

KIWI UI를 통하지 않고 CLI로 즉시 롤백해야 하는 긴급 상황을 위한 가이드입니다.

즉시 롤백 (Kubernetes)​

# KIWI의 Operate > Execute 탭에서 실행하거나 kubectl 직접 사용
kubectl rollout undo deployment/<deployment-name> -n <namespace>

특정 버전으로 롤백​

# 먼저 이력 확인
kubectl rollout history deployment/<deployment-name> -n <namespace>

# 특정 리비전으로 롤백
kubectl rollout undo deployment/<deployment-name> --to-revision=<revision-number> -n <namespace>
긴급 롤백 후 조치

CLI로 직접 롤백한 경우 KIWI의 배포 상태와 실제 상태가 일시적으로 불일치할 수 있습니다. 상황이 안정되면 KIWI에서 상태를 동기화하세요.

롤백 시 주의사항​

데이터베이스 마이그레이션​

롤백 전 반드시 확인하세요:

  • 스키마 변경: 새 버전에서 테이블/컬럼이 추가/변경되었는지 확인합니다 .
  • 데이터 호환성: 새 형식으로 저장된 데이터가 이전 버전과 호환되는지 확인합니다 .
  • 마이그레이션 롤백: DB 마이그레이션도 함께 롤백해야 하는지 검토합니다 .
파괴적 마이그레이션 주의

컬럼 삭제나 타입 변경 같은 파괴적 마이그레이션이 적용되었다면 단순 롤백이 어려울 수 있습니다. DB 백업을 확인하고 DBA와 상의하세요.

설정 변경​

롤백 시 함께 확인해야 할 설정:

  • 환경 변수: 이전 버전에서 필요한 환경 변수가 모두 있나요?
  • ConfigMap: 설정값이 이전 버전과 호환되나요?
  • Secret: 인증 정보가 변경되지 않았나요?

외부 서비스 연동​

  • 외부 API 버전이 변경되었다면 호환성 확인
  • 다른 마이크로서비스와의 통신 프로토콜 확인

롤백 실패 시 대처​

이전 이미지가 없는 경우​

  • 레지스트리에서 삭제된 경우: 이전 버전 소스 코드에서 재빌드합니다 .
  • 태그가 덮어쓰기된 경우: 이미지 다이제스트(SHA)로 복원을 시도합니다 .
이미지 다이제스트로 복원

Harbor나 Docker Hub에서 이미지의 다이제스트(SHA256)를 확인하면 덮어쓰기된 태그도 특정 버전으로 복원할 수 있습니다.

롤백 후에도 문제 지속​

  1. 로그 분석: 애플리케이션 로그에서 근본 원인 파악
  2. 환경 확인: 환경 변수, ConfigMap, Secret 설정 검토
  3. 외부 의존성: 데이터베이스, 외부 API 상태 확인
  4. 더 이전 버전: 필요시 더 이전의 안정 버전으로 롤백

롤백 방지 모범 사례​

롤백이 필요한 상황을 줄이기 위한 권장 사항입니다.

배포 전 검증 체크리스트​

  • 빌드 단계: 테스트 통과, 보안 스캔 통과
  • 스테이징 단계: 기능 테스트, 성능 테스트
  • 카나리 단계: 일부 트래픽으로 실제 환경 검증
  • 프로덕션 단계: 모니터링 대시보드, 알림 설정

자동 롤백 설정 (Kubernetes)​

Kubernetes에서 자동 롤백 조건을 설정할 수 있습니다:

  • Pod 시작 실패 시: progressDeadlineSeconds 설정
  • Health Check 실패 시: readinessProbe, livenessProbe 설정
  • 리소스 한도 초과 시: resources.limits 설정
점진적 롤아웃

maxUnavailable: 0으로 설정하면 새 Pod이 Ready 상태가 될 때까지 기존 Pod을 유지합니다. 문제 발생 시 자동으로 롤백됩니다.

관련 가이드​