본문으로 건너뛰기

복구

백업 데이터를 사용하여 시스템을 이전 상태로 복구하는 방법을 안내합니다. KIOPS 코드의 라벨은 복구 이력(restoration history)으로 통일되어 있습니다.

복구는 언제 필요한가요?

  • 시스템 장애: 서버 장애, 디스크 손상 등으로 데이터가 손실된 경우
  • 실수로 인한 삭제: 중요한 리소스나 데이터를 잘못 삭제한 경우
  • 업데이트 롤백: 문제가 있는 업데이트를 이전 상태로 되돌리는 경우
  • 환경 복제: 백업을 사용하여 동일한 환경을 다른 곳에 구성하는 경우

복구 유형​

KIOPS에서 지원하는 복구 흐름은 다음과 같습니다.

  • Velero 복구: Velero 백업에서 네임스페이스/리소스 단위로 워크로드와 PV 데이터를 복구합니다.
  • 컨트롤 플레인 복구: etcd 스냅샷과 PKI 인증서가 포함된 컨트롤 플레인 백업에서 클러스터를 복구합니다.
  • Docker/Podman 복구: 볼륨, 설정, 컨테이너를 복구합니다.
복구 전 주의사항
  • 복구 작업은 현재 데이터를 덮어쓸 수 있습니다. 필요하다면 복구 전에 현재 상태를 백업하세요.
  • 가능하면 서비스 사용량이 적은 시간에 복구를 진행하세요.
  • 운영 환경에서는 테스트 환경에서 먼저 복구를 검증한 후 진행하세요.

Velero 복구​

Velero 백업에서 워크로드와 PV 데이터를 복구합니다. 복구는 복구 마법사로 진행되며, 연결 방식 선택 → SSH 자격증명 → 복구 설정 순으로 이어집니다.

Step 1: 백업 선택 및 복구 시작​

  1. [백업 관리] > 백업 목록 탭에서 K8s 백업 세그먼트를 Velero로 둔 채 복구할 백업 행을 찾습니다.
  2. 해당 행의 복원 아이콘을 클릭합니다.

Step 2: 복구 설정​

마지막 복구 설정 단계에서 다음 옵션을 지정합니다.

옵션설명
복구할 네임스페이스 선택다중 네임스페이스 백업이면 백업에 포함된 네임스페이스 중 복구할 대상을 선택하여(최소 1개) 일부만 복구할 수 있습니다. 단일 네임스페이스 백업은 원본→대상 네임스페이스 이름 매핑이 가능합니다.
리소스 복원 범위무엇을 되돌릴지 선택합니다(아래 4가지).
PVC 데이터 복원백업에 PVC 볼륨 데이터가 포함된 경우에만 표시됩니다. 해제하면 K8s 리소스(Deployment, Service 등)만 복원합니다.

리소스 복원 범위(4가지)

  • 전체 리소스: 백업된 모든 리소스를 복원합니다.
  • PV/PVC 제외: PV/PVC 객체 자체는 복원하지 않고 기존 스토리지를 유지합니다.
  • 앱 리소스만: Deployment, Service, ConfigMap, Secret 등만 복원합니다.
  • 직접 선택: 복원할 리소스 종류를 직접 선택하여 복원합니다.

리소스 필터는 복구 시 선택합니다 — 백업은 선택한 네임스페이스 전체를 담고, 어떤 리소스를 되돌릴지는 이 리소스 복원 범위에서 좁힙니다. PV/PVC 제외는 기존 운영 중인 볼륨을 보존하면서 워크로드만 되돌릴 때 유용합니다.

Step 3: 복구 실행 및 확인​

  1. 옵션을 확인한 뒤 복구 시작을 클릭합니다.
  2. 복구 진행 상태는 복구 이력 탭(Velero 세그먼트)에서 실시간으로 확인할 수 있습니다.
  3. 완료 후 kubectl get pods -n <네임스페이스>로 워크로드가 정상 기동했는지 확인합니다.

컨트롤 플레인 복구​

etcd 스냅샷과 PKI 인증서를 포함한 컨트롤 플레인 백업에서 클러스터를 복구합니다.

주의: 클러스터 전체 교체

컨트롤 플레인 복구는 클러스터를 선택한 백업 시점으로 완전히 교체합니다. 복구 이후의 모든 변경사항(리소스 생성/수정/삭제)이 사라집니다. 반드시 현재 상태를 먼저 백업한 후 진행하세요.

컨트롤 플레인 복구는 복구 마법사로 진행되며, 연결 방식 선택 → SSH 자격증명 → 확인 단계로 이어집니다.

Step 1: 백업 선택 및 복원 아이콘 클릭​

  1. 좌측 메뉴에서 [백업 관리]를 클릭합니다.
  2. 백업 목록 탭에서 K8s 백업 세그먼트를 컨트롤플레인으로 전환한 뒤 복구할 백업 행을 찾습니다.
  3. 해당 행의 복원 아이콘을 클릭합니다.

Step 2: 연결 방식 선택 및 SSH 자격증명 입력​

복구는 마스터 노드에 SSH로 직접 접속하여 수행됩니다. 먼저 연결 방식(직접 SSH / VPN 경유)을 선택한 뒤, SSH 접속 정보를 입력합니다. 게이트웨이를 경유하는 다중 홉 SSH를 지원합니다.

  • SSH 접속 정보: 마스터 노드(및 경유 게이트웨이)의 호스트/포트/사용자명/비밀번호
  • sudo 비밀번호: etcd 정지/복원 및 PKI 적용을 위해 sudo 비밀번호를 입력합니다.

Step 3: 확인 텍스트 입력 후 복구 실행​

복원 버튼은 확인을 위해 백업 이름을 정확히 입력해야 활성화됩니다. 백업 이름을 그대로 입력한 뒤 복구 시작을 클릭합니다. (이 작업은 클러스터를 선택한 백업 시점으로 완전히 교체합니다.)

Step 4: 복구 진행 및 완료 확인​

  1. 백엔드가 오브젝트 스토리지에서 백업 번들을 다운로드합니다.
  2. etcd 복구(etcdctl snapshot restore)와 PKI 인증서 복원이 차례로 수행됩니다.
  3. 완료 후 복구 이력 탭에서 결과 상태를 확인합니다.

Step 5: 클러스터 상태 확인​

복구가 완료되면 클러스터가 정상 작동하는지 확인합니다.

kubectl get nodes
kubectl get pods --all-namespaces
kubectl get pods -n kube-system

복구 후 체크리스트

  1. 모든 노드가 Ready 상태인가요?
  2. kube-system Pod들이 모두 Running 상태인가요?
  3. 애플리케이션 Pod들이 정상적으로 실행 중인가요?
  4. 서비스에 정상적으로 접근할 수 있나요?

Docker/Podman 복구​

Docker/Podman 백업에서 볼륨, 설정, 컨테이너를 복구합니다. 복구 옵션은 아래 네 가지입니다.

복구 옵션 (UI)​

UI 필드 라벨옵션 키설명
볼륨 데이터 복구restoreVolumes컨테이너에 마운트된 볼륨 데이터를 복구합니다.
네트워크 설정 복구restoreNetworks컨테이너 네트워크 설정을 복구합니다.
기존 컨테이너 덮어쓰기overwriteExisting동일한 이름의 기존 컨테이너를 삭제 후 재생성합니다.
복구할 컨테이너selectedContainers선택한 컨테이너만 복구합니다(미선택 시 전체).

화면에 없는 세 가지 동작은 고정값으로 처리됩니다. 설정은 항상 복구되고, Compose 재배포와 기존 컨테이너 중지는 수행되지 않습니다.

위치 옵션 안내 — 가이드 이전 버전의 "원래 위치 / 새 위치" 옵션은 백엔드 모델에 존재하지 않습니다. 별도의 "이미지 복구(docker load)" 흐름도 제공되지 않습니다.

복구 절차​

  1. [백업 관리] > 백업 목록 탭에서 대상 Docker/Podman 백업 행을 찾습니다. 복구 이력 탭은 결과 조회 전용이며 복구 시작 액션이 없으므로, 복구 시작은 반드시 백업 목록 탭의 백업 행에서 수행해야 합니다.
  2. 백업 행의 복원 아이콘을 클릭해 복구 모달을 엽니다.
  3. 위 옵션(볼륨 데이터 복구 / 네트워크 설정 복구 / 기존 컨테이너 덮어쓰기)을 설정합니다.
  4. 필요 시 열리는 원격 연결 창에서 SSH 인증 정보를 입력합니다.
  5. 복구 시작을 클릭합니다.

컨테이너 복구 상세​

복구가 시작되면 복구 상세 창에서 다음 정보를 확인할 수 있습니다.

  • 복구 시작/종료 시간
  • 선택한 옵션 요약
  • 진행 단계별 로그
  • 최종 상태 (pending, in_progress, completed, failed)

복구 이력​

[백업 관리] > 복구 이력 탭에서 모든 복구 작업의 결과를 추적할 수 있습니다.

  • 상태값: pending, in_progress, completed, failed
  • 상세 보기: 행을 클릭하면 컨테이너 복구 상세 또는 컨트롤 플레인 복구 상세가 열립니다.
  • Compose 프로젝트 필터: Docker/Podman 복구 이력을 Docker Compose 프로젝트 이름별로 필터링합니다. 여러 프로젝트를 함께 운영하는 Docker 호스트에서 특정 프로젝트의 복구 이력만 모아 볼 때 유용합니다.

복구 검증​

복구 후에는 반드시 시스템이 정상적으로 작동하는지 검증합니다.

검증 체크리스트​

  • 서비스 상태: Pod/컨테이너 상태를 확인합니다. Running 상태여야 정상입니다.
  • 데이터 무결성: 애플리케이션 데이터를 확인합니다. 백업 시점의 데이터가 존재해야 합니다.
  • 네트워크: 서비스 접근을 테스트합니다. 정상 응답이 와야 합니다.
  • 로그: 애플리케이션 로그를 확인합니다. 오류가 없어야 합니다.

복구 검증 자동화 — 중요한 시스템에서는 복구 후 자동으로 헬스체크를 수행하는 스크립트를 준비해두면 검증 시간을 단축할 수 있습니다.

문제 해결​

복구 실패: "snapshot file corrupted"​

restore failed: snapshot file corrupted

왜 발생하나요? 백업 파일이 손상되어 복구에 사용할 수 없습니다.

해결 방법

  1. 다른 백업 파일 사용: 다른 날짜의 정상적인 백업을 선택하세요.
  2. 백업 파일 무결성 검사: 저장소 측 체크섬을 확인하세요.
  3. 원본 백업 복사본 확인: 다른 위치에 복제된 백업이 있다면 해당 파일을 사용하세요.

SSH 인증 실패​

마스터 노드 SSH 자격증명이 잘못되었거나, 권한이 부족한 경우입니다. 입력한 SSH 사용자명, 비밀번호, sudo 비밀번호가 올바른지 다시 확인하세요.

데이터 불일치​

복구 후 예상과 다른 데이터가 표시되거나, 애플리케이션이 오류를 발생시키는 경우입니다.

확인 및 해결 방법

  1. 백업 시점 확인: 복구된 데이터가 백업 시점의 상태인지 확인하세요.
  2. 스키마 호환성 확인: 애플리케이션 버전과 데이터 스키마가 호환되는지 확인하세요.
  3. 외부 시스템 동기화: 데이터베이스 등 외부 시스템도 함께 복구가 필요한지 확인하세요.

부분 복구 주의 — 시스템의 일부만 복구하면 데이터 불일치가 발생할 수 있습니다. 가능하면 관련된 모든 구성요소를 함께 복구하세요.