롤백
배포 후 문제가 발생했나요? 롤백을 사용하면 빠르게 직전 버전으로 복원할 수 있습니다. 새 버전에서 버그가 발견되었거나 성능 문제가 있을 때, 몇 번의 클릭만으로 안정된 이전 버전으로 돌아갈 수 있습니다.
- Kubernetes: 운영 모달의 배포 관리 탭에 즉시 롤백 버튼이 있습니다(
kubectl rollout undo). - Docker · Podman: 별도의 롤백 전용 UI가 없습니다. Deploy 단계에서 이전 이미지 태그를 선택해 재배포하는 방식으로 롤백합니다.
- 새 버전 배포 후 예상치 못한 오류가 발생했을 때
- 성능 저하나 메모리 누수가 발견되었을 때
- 외부 서비스와의 호환성 문제가 발생했을 때
- 사용자로부터 심각한 버그 리포트가 들어왔을 때
롤백 개요
런타임별로 롤백 방식이 다릅니다.
- Kubernetes: 운영 모달의 배포 관리 탭에서 즉시 롤백 버튼으로 직전 리비전으로 되돌립니다. 내부적으로
kubectl rollout undo가 실행됩니다. - Docker: 별도의 롤백 전용 UI는 없습니다. Deploy 단계에서 이전 이미지 태그를 선택해 재배포하는 방식으로 롤백합니다.
KIOPS UI에서는 직전 리비전(N-1) 으로만 자동 롤백할 수 있습니다. 더 이전 리비전으로 되돌리려면 운영 모달의 명령 실행 탭에서 kubectl rollout undo --to-revision=N 명령을 직접 실행해야 합니다.
Kubernetes 롤백
Step 1: 배포 이력 확인
- [서비스 관리] 페이지에서 서비스의 운영 카드를 클릭합니다.
- 운영 모달에서 배포 관리 탭을 선택합니다.
- 히스토리 조회 버튼을 클릭하면
kubectl rollout history명령의 출력이 그대로 TextArea에 표시됩니다.
롤아웃 이력 출력 예시
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 2: 즉시 롤백 실행
- 히스토리 출력을 보고 직전 리비전으로 되돌릴지 결정합니다.
- 즉시 롤백 버튼을 클릭합니다.
- 확인 대화상자에서 진행을 승인하면 백엔드가
kubectl rollout undo deployment/<name> -n <namespace>명령을 실행합니다.
KIOPS UI에서는 특정 리비전을 골라서 롤백할 수 없습니다. 즉시 롤백 버튼은 항상 --to-revision 인자 없이 호출되어 직전 리비전(N-1) 으로만 되돌립니다.
Step 3: 롤백 결과 확인
롤백이 완료되면 운영 모달의 파드 목록 탭에서 새 ReplicaSet이 정상적으로 기동되었는지 확인합니다.
- 모든 Pod 상태가 Running 인지
- 서비스 응답이 정상인지 (Health Check 통과)
- 로그에 오류가 없는지
- 주요 기능이 정상 동작하는지
Docker · Podman 롤백
Docker·Podman 환경에는 별도의 롤백 전용 UI가 없습니다. 이전에 성공한 이미지 태그를 선택해 다시 배포하면 롤백 효과를 얻을 수 있습니다.
Step 1: 이전 이미지 태그 확인
- [서비스 관리] 페이지에서 서비스를 선택합니다.
- 빌드 이력 또는 컨테이너 레지스트리에서 이전에 정상 동작했던 이미지 태그를 확인합니다.
태그 형식이 ${BRANCH}-${SHORT_SHA}라면 이전 커밋의 해시로 찾을 수 있습니다.
Step 2: 이전 이미지 재배포
- 파이프라인의 Deploy 단계를 클릭합니다.
- DockerDeployModal에서 이미지 버전을 이전 버전으로 변경합니다.
- 배포 전 자동 백업 옵션이 켜져 있는지 확인합니다. 켜져 있으면 재배포 직전 상태가 백업되어, 재배포 실패 시 직전 상태로 복원할 수 있습니다.
- 배포 버튼을 클릭합니다.
Step 3: 컨테이너 상태 확인
운영 모달의 컨테이너 목록 탭에서 새 컨테이너가 Running 상태인지, 로그에 오류가 없는지 확인합니다.
더 이전 리비전으로 롤백 (긴급/수동)
KIOPS UI의 즉시 롤백 버튼으로는 직전 리비전으로만 되돌릴 수 있습니다. 두 단계 이상 이전의 리비전으로 되돌리려면 다음과 같이 명령을 직접 실행하세요.
운영 모달 - 명령 실행 탭에서 실행
- 운영 모달의 명령 실행 탭으로 이동합니다.
- 다음 명령으로 리비전 목록을 확인합니다.
kubectl rollout history deployment/<deployment-name> -n <namespace>
- 원하는 리비전 번호를 골라 롤백합니다.
kubectl rollout undo deployment/<deployment-name> --to-revision=<revision-number> -n <namespace>
명령 실행 탭에서 직접 롤백한 경우, KIOPS의 배포 이력 표시와 실제 클러스터 상태가 일시적으로 불일치할 수 있습니다. 운영 모달의 파드 목록 탭에서 실제 Pod 상태를 확인하고, 필요하면 히스토리 조회 버튼으로 최신 이력을 다시 가져오세요.
롤백 시 주의사항
데이터베이스 마이그레이션
롤백 전 반드시 확인하세요.
- 스키마 변경: 새 버전에서 테이블/컬럼이 추가/변경되었는지 확인합니다.
- 데이터 호환성: 새 형식으로 저장된 데이터가 이전 버전과 호환되는지 확인합니다.
- 마이그레이션 롤백: DB 마이그레이션도 함께 롤백해야 하는지 검토합니다.
컬럼 삭제나 타입 변경 같은 파괴적 마이그레이션이 적용되었다면 단순 롤백이 어려울 수 있습니다. DB 백업을 확인하고 DBA와 상의하세요.
설정 변경
롤백 시 함께 확인해야 할 설정.
- 환경 변수: 이전 버전에서 필요한 환경 변수가 모두 있나요?
- ConfigMap: 설정값이 이전 버전과 호환되나요?
- Secret: 인증 정보가 변경되지 않았나요?
외부 서비스 연동
- 외부 API 버전이 변경되었다면 호환성 확인
- 다른 마이크로서비스와의 통신 프로토콜 확인
롤백 실패 시 대처
이전 이미지가 없는 경우
- 레지스트리에서 삭제된 경우: 이전 버전 소스 코드에서 재빌드합니다.
- 태그가 덮어쓰기된 경우: 이미지 다이제스트(SHA)로 복원을 시도합니다.
Harbor나 Docker Hub에서 이미지의 다이제스트(SHA256)를 확인하면 덮어쓰기된 태그도 특정 버전으로 복원할 수 있습니다.
Docker 재배포가 실패한 경우
배포 전 자동 백업 옵션이 켜져 있었다면, 백업 시점의 컨테이너/볼륨 상태로 복원할 수 있습니다. [백업 관리] 페이지에서 해당 백업을 선택해 복원을 진행하세요.
롤백 후에도 문제 지속
- 로그 분석: 애플리케이션 로그에서 근본 원인 파악
- 환경 확인: 환경 변수, ConfigMap, Secret 설정 검토
- 외부 의존성: 데이터베이스, 외부 API 상태 확인
- 더 이전 버전: 필요시 명령 실행 탭에서 더 이전 리비전으로 롤백
롤백 방지 모범 사례
롤백이 필요한 상황을 줄이기 위한 권장 사항입니다.
배포 전 검증 체크리스트
- 빌드 단계: 테스트 통과, 보안 스캔 통과
- 스테이징 단계: 기능 테스트, 성능 테스트
- 카나리 단계: 일부 트래픽으로 실제 환경 검증
- 프로덕션 단계: 모니터링 대시보드, 알림 설정
무중단 롤아웃 설정 (Kubernetes)
Kubernetes에서 안정적인 롤아웃을 위해 권장하는 설정.
- Pod 시작 실패 대비:
progressDeadlineSeconds설정 - Health Check:
readinessProbe,livenessProbe설정 - 리소스 보호:
resources.limits설정
maxUnavailable: 0으로 설정하면 새 Pod이 Ready 상태가 될 때까지 기존 Pod을 유지합니다. 문제 발생 시 새 Pod이 Ready로 전환되지 않아 기존 Pod이 유지됩니다.