복구
백업 데이터를 사용하여 시스템을 이전 상태로 복구하는 방법을 안내합니다. KIOPS 코드의 라벨은 복구 이력(restoration history)으로 통일되어 있습니다.
- 시스템 장애: 서버 장애, 디스크 손상 등으로 데이터가 손실된 경우
- 실수로 인한 삭제: 중요한 리소스나 데이터를 잘못 삭제한 경우
- 업데이트 롤백: 문제가 있는 업데이트를 이전 상태로 되돌리는 경우
- 환경 복제: 백업을 사용하여 동일한 환경을 다른 곳에 구성하는 경우
복구 유형
KIOPS에서 지원하는 복구 흐름은 다음과 같습니다.
- 컨트롤 플레인 복구: etcd 스냅샷과 PKI 인증서가 포함된 컨트롤 플레인 백업에서 클러스터를 복구합니다.
- Docker/Podman 복구: 볼륨, 설정, 컨테이너를 복구합니다.
- 복구 작업은 현재 데이터를 덮어쓸 수 있습니다. 필요하다면 복구 전에 현재 상태를 백업하세요.
- 가능하면 서비스 사용량이 적은 시간에 복구를 진행하세요.
- 운영 환경에서는 테스트 환경에서 먼저 복구를 검증한 후 진행하세요.
컨트롤 플레인 복구
etcd 스냅샷과 PKI 인증서를 포함한 컨트롤 플레인 백업에서 클러스터를 복구합니다.
컨트롤 플레인 복구는 클러스터를 선택한 백업 시점으로 완전히 교체합니다. 복구 이후의 모든 변경사항(리소스 생성/수정/삭제)이 사라집니다. 반드시 현재 상태를 먼저 백업한 후 진행하세요.
Step 1: 백업 선택 및 복구 아이콘 클릭
- 좌측 메뉴에서 **[백업 관리]**를 클릭합니다.
- 백업 목록 탭에서 K8s 백업 세그먼트를 컨트롤플레인으로 전환한 뒤 복구할 백업 행을 찾습니다.
- 해당 행의 복원 아이콘을 클릭합니다.
Step 2: ControlplaneRestoreModal에서 SSH 자격증명 입력
복구는 마스터 노드에 SSH로 직접 접속하여 수행됩니다.
- SSH 사용자명: 마스터 노드 SSH 계정
- SSH 비밀번호: 마스터 노드 SSH 비밀번호
- sudo 비밀번호: etcd 정지/복원 및 PKI 적용을 위해 sudo 비밀번호를 입력합니다.
Step 3: 확인 텍스트 입력 후 복구 실행
복원 버튼은 확인을 위해 백업 이름을 정확히 입력해야 활성화됩니다. 백업 이름을 그대로 입력한 뒤 복구 시작을 클릭합니다. (이 작업은 클러스터를 선택한 백업 시점으로 완전히 교체합니다.)
Step 4: 복구 진행 및 완료 확인
- 백엔드가 오브젝트 스토리지에서 백업 번들을 다운로드합니다.
- etcd 복구(
etcdctl restore) 및 PKI 인증서 복원이 순차적으로 수행됩니다. - 완료 후 복구 이력 탭에서 결과 상태를 확인합니다.
Step 5: 클러스터 상태 확인
복구가 완료되면 클러스터가 정상 작동하는지 확인합니다.
kubectl get nodes
kubectl get pods --all-namespaces
kubectl get pods -n kube-system
- 모든 노드가
Ready상태인가요? - kube-system Pod들이 모두
Running상태인가요? - 애플리케이션 Pod들이 정상적으로 실행 중인가요?
- 서비스에 정상적으로 접근할 수 있나요?
Docker/Podman 복구
Docker/Podman 백업에서 볼륨, 설정, 컨테이너를 복구합니다. 복구 옵션은 백엔드의 DockerRestore 모델 필드를 그대로 반영합니다.
복구 옵션 (UI)
| UI 필드 라벨 | 옵션 키 | 설명 |
|---|---|---|
| 볼륨 데이터 복구 | restoreVolumes | 백업된 볼륨 데이터를 복원합니다. |
| 설정 파일 복구 | restoreConfig | docker-compose 등 설정 파일을 복원합니다. |
| 서비스 재배포 (롤백) | redeployCompose | 복원된 설정으로 컴포즈 스택을 재배포합니다. |
| 기존 서비스 중지 | stopExisting | 복구 전에 기존 실행 중 컨테이너를 중지합니다. |
가이드 이전 버전의 "원래 위치 / 새 위치" 옵션은 백엔드 모델에 존재하지 않습니다. 또한 별도의 "이미지 복구(docker load)" 흐름도 DockerRestore 모델에는 image 필드가 없으므로 제공되지 않습니다.
복구 절차
- [백업 관리] > 백업 목록 탭에서 대상 Docker/Podman 백업 행을 찾습니다. 복구 이력 탭은 결과 조회 전용이며 복구 시작 액션이 없으므로, 복구 시작은 반드시 백업 목록 탭의 백업 행에서 수행해야 합니다.
- 백업 행의 복구 아이콘을 클릭하여 복구 모달을 엽니다.
- 위 옵션(볼륨 데이터 복구 / 설정 파일 복구 / 서비스 재배포 (롤백) / 기존 서비스 중지)을 설정합니다.
- 필요 시 RemoteConnectionModal에서 SSH 인증을 입력합니다.
- 복구 시작을 클릭합니다.
DockerRestoreDetailModal
복구가 시작되면 DockerRestoreDetailModal에서 다음 정보를 확인할 수 있습니다.
- 복구 시작/종료 시간
- 선택한 옵션 요약
- 진행 단계별 로그
- 최종 상태 (
pending,in_progress,completed,failed)
복구 이력
[백업 관리] > 복구 이력 탭에서 모든 복구 작업의 결과를 추적할 수 있습니다.
- 상태값:
pending,in_progress,completed,failed - 상세 보기: 행을 클릭하면 DockerRestoreDetailModal 또는 컨트롤 플레인 복구 상세가 열립니다.
- Compose 프로젝트 필터: Docker/Podman 복구 이력을 Docker Compose 프로젝트 이름별로 필터링합니다. 여러 프로젝트를 함께 운영하는 Docker 호스트에서 특정 프로젝트의 복구 이력만 모아 볼 때 유용합니다.
복구 검증
복구 후에는 반드시 시스템이 정상적으로 작동하는지 검증합니다.
검증 체크리스트
- 서비스 상태: Pod/컨테이너 상태를 확인합니다. Running 상태여야 정상입니다.
- 데이터 무결성: 애플리케이션 데이터를 확인합니다. 백업 시점의 데이터가 존재해야 합니다.
- 네트워크: 서비스 접근을 테스트합니다. 정상 응답이 와야 합니다.
- 로그: 애플리케이션 로그를 확인합니다. 오류가 없어야 합니다.
중요한 시스템에서는 복구 후 자동으로 헬스체크를 수행하는 스크립트를 준비해두면 검증 시간을 단축할 수 있습니다.
문제 해결
복구 실패: "snapshot file corrupted"
restore failed: snapshot file corrupted
왜 발생하나요? 백업 파일이 손상되어 복구에 사용할 수 없습니다.
해결 방법
- 다른 백업 파일 사용: 다른 날짜의 정상적인 백업을 선택하세요.
- 백업 파일 무결성 검사: 저장소 측 체크섬을 확인하세요.
- 원본 백업 복사본 확인: 다른 위치에 복제된 백업이 있다면 해당 파일을 사용하세요.
SSH 인증 실패
마스터 노드 SSH 자격증명이 잘못되었거나, 권한이 부족한 경우입니다. 입력한 SSH 사용자명, 비밀번호, sudo 비밀번호가 올바른지 다시 확인하세요.
데이터 불일치
복구 후 예상과 다른 데이터가 표시되거나, 애플리케이션이 오류를 발생시키는 경우입니다.
확인 및 해결 방법
- 백업 시점 확인: 복구된 데이터가 백업 시점의 상태인지 확인하세요.
- 스키마 호환성 확인: 애플리케이션 버전과 데이터 스키마가 호환되는지 확인하세요.
- 외부 시스템 동기화: 데이터베이스 등 외부 시스템도 함께 복구가 필요한지 확인하세요.
시스템의 일부만 복구하면 데이터 불일치가 발생할 수 있습니다. 가능하면 관련된 모든 구성요소를 함께 복구하세요.