본문으로 건너뛰기

롤백

배포한 새 버전에 버그가 발견되었거나 성능 문제가 생기면, 운영 모달의 명령 실행 탭에서 명령 한 줄로 직전 버전으로 되돌릴 수 있습니다.

롤백은 다음과 같은 상황에서 필요합니다.

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

롤백 개요​

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

  • Kubernetes: 전용 롤백 버튼은 없습니다. 운영 모달의 명령 실행 탭에서 kubectl rollout undo 를 직접 실행해 롤백합니다.
  • Docker: 별도의 롤백 전용 UI는 없습니다. 배포 단계에서 이전 이미지 태그를 선택해 재배포하는 방식으로 롤백합니다.

Kubernetes 롤백​

KIOPS UI에는 전용 즉시 롤백 버튼이나 배포 관리 탭이 없습니다(service:deploy:rollback 권한은 정의되어 있으나 UI 미구현). Kubernetes 롤백은 운영 모달의 명령 실행 탭에서 kubectl 명령을 직접 실행해 수행합니다.

Step 1: 운영 진입 및 명령 실행 탭 이동​

  1. [서비스 관리] 페이지에서 서비스의 운영 카드를 클릭합니다.
  2. 운영 모달에서 명령 실행 탭을 선택합니다.

Step 2: 배포 이력 확인​

다음 명령으로 리비전 목록을 확인합니다.

kubectl rollout history deployment/<deployment-name> -n <namespace>

롤아웃 이력 출력 예시​

deployment.apps/my-app
REVISION  CHANGE-CAUSE
3         kubectl set image deployment/my-app api=registry/api:v1.0.2
4         kubectl set image deployment/my-app api=registry/api:v1.0.3
5         kubectl set image deployment/my-app api=registry/api:v1.0.4
  • 정형화된 테이블이 아니라 kubectl 명령의 표준 출력이 그대로 표시됩니다.
  • REVISION 번호가 가장 큰 항목이 현재 배포된 버전이고, 그 바로 앞 번호가 직전 버전입니다.
  • CHANGE-CAUSE 컬럼에는 배포 시 기록된 명령 또는 어노테이션이 표시됩니다.

Step 3: 롤백 실행​

직전 리비전으로 되돌리려면 다음 명령을 실행합니다.

kubectl rollout undo deployment/<deployment-name> -n <namespace>

특정 리비전으로 되돌리려면 --to-revision=<번호> 인자를 추가합니다.

kubectl rollout undo deployment/<deployment-name> --to-revision=<revision-number> -n <namespace>

Step 4: 롤백 결과 확인​

롤백이 완료되면 운영 모달의 파드 목록 탭에서 새 ReplicaSet이 정상적으로 기동되었는지 확인합니다.

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

Docker · Podman 롤백​

Docker·Podman 환경에는 별도의 롤백 전용 UI가 없습니다. 이전에 성공한 이미지 태그를 선택해 다시 배포하면 롤백 효과를 얻을 수 있습니다.

Step 1: 이전 이미지 태그 확인​

  1. [서비스 관리] 페이지에서 서비스를 선택합니다.
  2. 빌드 이력 또는 컨테이너 레지스트리에서 이전에 정상 동작했던 이미지 태그를 확인합니다. 태그 형식이 ${BRANCH}-${SHORT_SHA}라면 이전 커밋의 해시로 찾을 수 있습니다.

Step 2: 이전 이미지 재배포​

  1. 파이프라인의 배포 단계를 클릭합니다.
  2. 배포 모달에서 이미지 버전을 이전 버전으로 변경합니다.
  3. 배포 전 자동 백업 옵션이 켜져 있는지 확인합니다. 켜져 있으면 재배포 직전 상태가 백업되어, 재배포 실패 시 직전 상태로 복원할 수 있습니다.
  4. 배포 버튼을 클릭합니다.

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

운영 모달의 컨테이너 목록 탭에서 새 컨테이너가 Running 상태인지, 로그에 오류가 없는지 확인합니다.

롤백 후 상태 확인​

명령 실행 탭에서 직접 롤백한 경우, KIOPS의 배포 이력 표시와 실제 클러스터 상태가 일시적으로 불일치할 수 있습니다. 운영 모달의 파드 목록 탭에서 실제 Pod 상태를 확인하고, 필요하면 명령 실행 탭에서 kubectl rollout history 명령으로 최신 이력을 다시 조회하세요.

롤백 시 주의사항​

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

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

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

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

설정 변경​

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

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

외부 서비스 연동​

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

롤백 실패 시 대처​

이전 이미지가 없는 경우​

  • 레지스트리에서 삭제된 경우: 이전 버전 소스 코드에서 재빌드합니다.
  • 태그가 덮어쓰기된 경우: 이미지 다이제스트(SHA)로 복원을 시도합니다. Harbor나 Docker Hub에서 이미지의 다이제스트(SHA256)를 확인하면 덮어쓰기된 태그도 특정 버전으로 복원할 수 있습니다.

Docker 재배포가 실패한 경우​

배포 전 자동 백업 옵션이 켜져 있었다면, 백업 시점의 컨테이너/볼륨 상태로 복원할 수 있습니다. [백업 관리] 페이지에서 해당 백업을 선택해 복원을 진행하세요.

롤백 후에도 문제 지속​

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

롤백 방지 모범 사례​

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

배포 전 검증 체크리스트​

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

무중단 롤아웃 설정 (Kubernetes)​

Kubernetes에서 안정적인 롤아웃을 위해 권장하는 설정.

  • Pod 시작 실패 대비: progressDeadlineSeconds 설정
  • Health Check: readinessProbe, livenessProbe 설정
  • 리소스 보호: resources.limits 설정
  • 점진적 롤아웃: maxUnavailable: 0으로 설정하면 새 Pod가 Ready 상태가 될 때까지 기존 Pod를 유지합니다. 문제 발생 시 새 Pod가 Ready로 전환되지 않아 기존 Pod가 유지됩니다.

관련 가이드​