Docker 백업
Docker 또는 Podman 환경에서 실행 중인 컨테이너와 볼륨, 설정을 안전하게 백업하는 방법을 안내합니다. 백업 생성 모달의 제목은 **"Docker/Podman 백업 생성"**이며, 런타임 종류(runtimeType === 'podman' 포함)를 자동 인식합니다.
Docker/Podman 컨테이너는 기본적으로 일시적(ephemeral)입니다. 컨테이너가 삭제되면 내부 데이터도 함께 사라집니다. 중요한 데이터가 있는 볼륨과 docker-compose 설정은 반드시 백업해두어야 장애 상황에서 빠르게 복구할 수 있습니다.
사전 필수 조건
Docker/Podman 백업을 생성하려면 외부 저장소가 사전에 등록되어 있어야 합니다.
- [백업 관리] > 저장소 관리 탭에서 외부 저장소를 등록합니다.
- InfraLinkModal을 통해 백업 대상 인프라(Docker/Podman 호스트)와 저장소를 연결합니다.
- 연결이 완료되면 백업 생성 마법사에서 해당 저장소가 선택지로 표시됩니다.
자세한 절차는 Velero/오브젝트 스토리지 설치 가이드를 참고하세요.
백업 유형과 백업 범위 (2축 구조)
KIOPS의 Docker/Podman 백업은 **백업 유형(무엇을 담을지)**과 **백업 범위(어디서 가져올지)**를 별도로 선택합니다.
백업 유형 (BackupOptionsModal)
내부 값은 full / volume / config / compose 이며, 사용자 화면에는 한국어 라벨로 표시됩니다.
- 전체 백업 (
full): 볼륨 + 컨테이너 설정 + Compose 파일 - 볼륨만 (
volume): 데이터 볼륨만 백업 - 설정만 (
config): 컨테이너 설정만 백업 - Compose 파일만 (
compose): docker-compose.yml 파일만 백업
서비스 단위 백업(ServiceBackupFormModal)에서는 추가로 docker-compose 정의도 함께 보관됩니다.
백업 범위
백업 범위는 3가지 라디오 옵션 중 하나로 선택합니다(BackupOptionsModal의 backupScope).
- 전체 컨테이너: 인프라의 모든 컨테이너/볼륨을 대상으로 합니다.
- Compose 프로젝트: 대상 호스트에서 실행 중인 Docker Compose 프로젝트 단위로 백업합니다. 컨테이너 레이블
com.docker.compose.project를 기준으로 프로젝트 목록이 조회됩니다. - 컨테이너 선택: 백업할 컨테이너를 직접 다중 선택합니다.
백엔드 모델에 독립적인 "이미지 백업" 타입은 존재하지 않습니다. 이미지 자체는 컨테이너 레지스트리에서 재획득하는 것을 전제로 합니다.
백업 절차
KIOPS의 [백업 관리] 페이지에서 Docker/Podman 백업을 생성합니다.
Step 1: 백업 관리 페이지 이동
- 좌측 메뉴에서 **[백업 관리]**를 클릭합니다.
- 상단의 백업 생성 버튼을 클릭합니다.
Step 2: 런타임과 저장소 선택
- 런타임: 백업할 Docker 또는 Podman 호스트를 선택합니다.
- 외부 저장소: InfraLinkModal로 미리 연결된 저장소 중 하나를 선택합니다.
런타임은 KIOPS에 등록된 Docker/Podman 호스트를 의미합니다. 여러 서버가 있다면 각각 다른 런타임으로 등록되어 있을 수 있습니다.
Step 3: 백업 유형 선택
위에서 설명한 full / volume / config / compose 중 하나를 선택합니다.
Step 4: 백업 범위 선택
백업 설정(BackupOptionsModal) 화면의 백업 범위 라디오에서 다음 3가지 중 하나를 선택합니다. SSH 접속 정보는 이전 마법사 단계에서 이미 입력했으므로, 범위를 전환하면 모달이 해당 목록을 자동으로 불러옵니다.
- 전체 컨테이너: 추가 입력 없이 진행합니다.
- Compose 프로젝트: 범위를 선택하면 대상 호스트의 Compose 프로젝트 목록이 자동 조회되어, 드롭다운에서 하나를 선택합니다.
- 컨테이너 선택: 범위를 선택하면 컨테이너 목록이 자동 조회되어, 체크박스로 하나 이상을 다중 선택합니다.
실행 중인 Compose 프로젝트 또는 컨테이너가 없으면 목록이 비어 있을 수 있습니다. 목록 옆 새로고침 버튼으로 다시 조회할 수 있습니다.
Step 5: 백업 실행
- 선택한 옵션을 확인합니다.
- 백업 시작 버튼을 클릭합니다.
- 백업 진행 상황이 화면에 표시됩니다.
볼륨 백업 시 해당 볼륨을 사용하는 컨테이너가 일시적으로 느려질 수 있습니다. 가능하면 서비스 사용량이 적은 시간에 백업을 실행하세요.
백엔드 메타데이터
생성된 백업 항목은 다음 메타데이터를 가집니다.
- storage_type: 사용된 외부 저장소 타입(예:
seaweedfs) - trigger_type: 다음 4가지 값 중 하나입니다 (
docker_backup.go:28기준).manual— 사용자가 모달에서 수동으로 실행pre_deploy— 배포 직전 자동 백업post_deploy— 배포 직후 자동 백업scheduled— 스케줄에 의한 자동 실행
- status:
pending,in_progress,completed,failed
상태값은 백업 목록과 복구 이력 탭에서 그대로 노출됩니다.
백업 목록 필터
Docker/Podman 백업 목록(BackupHierarchyView)에서는 다음 필터로 항목을 좁힐 수 있습니다.
- Compose 프로젝트 필터: Docker Compose 프로젝트 이름별로 백업 이력을 필터링합니다. 여러 프로젝트를 함께 운영하는 Docker 호스트에서 특정 프로젝트의 백업만 모아 볼 때 유용합니다.
- 유형 필터:
full / volume / config / compose등 백업 유형별로 목록을 필터링합니다.
백업 원리 이해하기
KIOPS가 내부적으로 어떻게 백업을 수행하는지 이해하면 문제 해결에 도움이 됩니다.
볼륨 백업 방식
볼륨은 임시 컨테이너를 생성하여 tar 파일로 압축합니다.
# KIOPS 내부 동작 예시
docker run --rm \
-v volume_name:/data \
-v /backup:/backup \
alpine tar cvf /backup/volume_backup.tar /data
설정 백업 방식
서비스 단위 백업 시 docker-compose.yml과 관련 설정 파일을 함께 묶어 보관합니다.
자동 백업과 trigger_type
Docker/Podman 백업 모달에는 매일/매주/매월 스케줄 UI가 없습니다. 라디오 기반 스케줄 입력은 K8s 백업의 레거시 BackupFormModal 에만 존재하며, Docker/Podman 백업은 모달에서 직접 스케줄을 설정할 수 없습니다.
대신 백엔드 trigger_type 메타데이터가 어떤 경로로 백업이 실행됐는지 구분합니다.
manual— 사용자가 모달에서 직접 실행pre_deploy/post_deploy— 배포 파이프라인이 자동으로 트리거scheduled— 별도 스케줄러에서 실행
배포 자동 백업(pre_deploy/post_deploy)을 활용하면 모달에서 별도 스케줄을 설정하지 않아도 변경 직전/직후 상태를 자동으로 보존할 수 있습니다.
문제 해결
볼륨 백업 실패: "volume is in use"
Error: volume is in use
왜 발생하나요? 다른 컨테이너가 해당 볼륨을 사용 중일 때 발생합니다. 데이터 정합성을 보장하기 위해 사용 중인 볼륨의 백업이 제한될 수 있습니다.
해결 방법
- 컨테이너 일시 중지: 해당 볼륨을 사용하는 컨테이너를 일시 중지한 후 백업을 다시 시도하세요.
- 저점 시간대 실행: 트래픽이 적은 시간대에 백업을 실행하세요.
디스크 공간 부족: "No space left on device"
No space left on device
왜 발생하나요? 백업 파일을 저장할 디스크 공간이 부족합니다. 특히 대용량 볼륨을 백업할 때 자주 발생합니다.
해결 방법
- 오래된 백업 정리: [백업 관리] 페이지에서 불필요한 백업을 삭제하세요.
- 외부 저장소 용량 확장: 등록된 외부 저장소의 용량을 확장하거나 다른 저장소로 변경하세요.
- 보관 기간 단축: 자동 백업의 보관 기간을 줄여 오래된 백업이 자동 삭제되도록 설정하세요.
백업 실패를 예방하려면 디스크 사용량을 정기적으로 확인하세요. 백업 저장 공간은 최소 전체 백업 크기의 2배 이상 여유를 확보하는 것이 좋습니다.