본문으로 건너뛰기

Velero/오브젝트 스토리지 설치

Kubernetes 클러스터의 백업 체계를 구축하기 위해 오브젝트 스토리지를 외부 저장소로 등록하고, Velero를 클러스터에 설치하는 방법을 안내합니다.

왜 Velero와 오브젝트 스토리지가 필요한가요? — etcd 스냅샷만으로는 Kubernetes 리소스의 정의만 백업됩니다. 실제 애플리케이션 데이터(PersistentVolume에 저장된 데이터)를 함께 백업하려면 Velero가 필요합니다. 오브젝트 스토리지(SeaweedFS)는 이 백업 데이터를 저장하는 S3 호환 스토리지 역할을 합니다.

KIOPS에서의 오브젝트 스토리지 위치 — KIOPS 백업 페이지에서 새 오브젝트 스토리지 자동 설치 또는 기존 저장소 등록을 선택할 수 있습니다. 자동 설치 시 SeaweedFS가 설치되며, AWS S3 등 다른 S3 호환 저장소는 직접 등록할 수 있습니다.

구성요소 이해하기​

오브젝트 스토리지 - 외부 저장소​

S3 호환 오브젝트 스토리지로, Velero가 생성한 백업 데이터를 저장합니다. KIOPS는 SeaweedFS 자동 설치를 지원하며, AWS S3 등 다른 S3 호환 저장소도 직접 등록할 수 있습니다.

  • S3 호환: AWS S3 API와 호환됩니다. 기존 S3 도구를 그대로 사용할 수 있습니다.
  • 온프레미스 친화: 외부 클라우드 의존 없이 사내 인프라에 백업 저장소를 구축할 수 있습니다.
  • 웹 콘솔: 브라우저 기반 관리 UI를 통해 버킷과 오브젝트를 직접 확인할 수 있습니다.

Velero - 백업 엔진​

Velero는 Kubernetes 리소스와 영구 볼륨을 백업·복원하는 오픈소스 도구입니다.

  • 클러스터 백업: 전체 또는 선택적 리소스를 백업합니다.
  • 재해 복구: 백업에서 클러스터를 복원합니다.
  • 마이그레이션: 클러스터 간 워크로드를 이전합니다.

사전 요구사항​

설치를 시작하기 전에 다음 조건을 확인하세요.

  • Kubernetes 클러스터: KIOPS에 등록되어 있어야 합니다. [런타임 환경] 페이지에서 확인할 수 있습니다.
  • 클러스터 관리자 권한: CRD 설치와 RBAC 생성 권한이 필요합니다.
  • 오브젝트 스토리지: 자동 설치(SeaweedFS)를 사용하거나, AWS S3 등 S3 호환 저장소를 직접 등록합니다. 직접 등록 시 엔드포인트 URL, Access Key, Secret Key, 버킷명을 미리 확보하세요.
  • 마스터 노드 SSH 비밀번호: Velero 설치 단계에서 입력이 필요합니다.

권한이 부족하다면? — [백업 관리] 메뉴가 보이지 않거나 접근이 거부된다면, 기관 관리자에게 권한을 요청하세요.

오브젝트 스토리지 자동 설치​

별도로 운영 중인 오브젝트 스토리지가 없다면 KIOPS에서 자동으로 설치할 수 있습니다. [백업 관리] > 저장소 관리 탭에서 새 오브젝트 스토리지 설치 버튼을 클릭하면 모달 제목이 "새 오브젝트 스토리지 설치"인 창이 열립니다.

설치 옵션​

  • 저장소 이름: 등록할 저장소를 식별할 이름입니다. (설명은 선택 입력)
  • 데이터 폴더 경로: 저장소 데이터가 저장될 절대 경로입니다. 필수이며 사전에 생성되어 있어야 합니다.
  • Access Key / Secret Key: 저장소 접근 자격증명입니다.
  • 버킷 이름: Velero 백업에 사용할 S3 버킷 이름입니다. 기본값: velero
  • S3 API 포트: S3 API 엔드포인트 포트입니다. 기본값: 8333
  • 설치 대상 서버: 오브젝트 스토리지를 설치할 서버(SSH 접속 경로)를 지정합니다.

자동 설치 구현체 — 자동 설치는 SeaweedFS를 기반으로 동작합니다. SeaweedFS는 S3 호환 API를 제공하는 경량 분산 오브젝트 스토리지입니다.

외부 저장소 등록​

KIOPS는 외부 저장소를 3단계로 등록합니다. [백업 관리] > 저장소 관리 탭에서 등록 버튼을 클릭하면 모달이 열립니다.

Step 1 - 기본 정보​

  • 이름: 저장소를 식별할 이름(예: object-storage-prod)
  • 타입: 오브젝트 스토리지 (SeaweedFS / MinIO 등 S3 호환) 선택 (내부값 minio, 기본값)
    • AWS S3, NFS 타입은 준비 중입니다.
  • 설명(선택): 운영 목적 등 메모

Step 2 - 연결 정보​

  • 엔드포인트: 예) http://your-storage-server:8333
  • Access Key: 오브젝트 스토리지 접근 ID
  • Secret Key: 오브젝트 스토리지 비밀 키
  • 버킷명: Velero가 사용할 버킷 이름(예: velero)

Step 3 - 등록 완료​

연결 테스트가 성공하면 외부 저장소 목록에 추가됩니다.

인증 정보 보관

Access Key와 Secret Key는 안전한 곳에 별도로 보관하세요. 분실 시 등록된 저장소의 인증을 갱신해야 합니다.

인프라와 외부 저장소 연결​

등록한 외부 저장소를 어느 인프라(런타임)에서 사용할지 지정해야 백업 시 선택 가능한 저장소로 표시됩니다.

  1. 저장소 관리 탭에서 대상 저장소의 연결 관리 아이콘을 클릭합니다.
  2. 열린 창에서 연결할 인프라(클러스터/호스트)를 선택합니다. 현재 선택 중인 인프라가 자동으로 미리 선택되어 표시되므로, 별도로 다시 고르지 않고 바로 연결할 수 있습니다.
  3. 저장 후, 해당 인프라의 백업 생성 마법사에서 이 저장소가 선택지로 표시됩니다.

인프라별 분리 사용 — 같은 오브젝트 스토리지를 여러 인프라에 연결하거나, 인프라마다 다른 저장소를 연결할 수 있습니다.

Velero 설치​

KIOPS의 Velero 설치는 단일 모달에서 진행됩니다. 다단계 마법사, 버전 선택, 볼륨 스냅샷 옵션, Provider/StorageClass 선택은 제공되지 않습니다.

진입 경로​

  • 경로 A: 백업 생성 시 Velero가 미설치된 경우 "Velero 미설치" 확인 후 설치 모달이 안내됩니다.
  • 경로 B: 인프라 설정 페이지 내 InfraVeleroSetting 상태 영역에서 직접 진입합니다.

설치 단계​

  1. 마스터 노드 자동 탐지: 선택한 클러스터의 마스터 노드를 자동으로 찾아 표시합니다. (마스터 노드: <서버명>)
  2. SSH 자격증명 입력: 마스터 노드 접속 정보를 입력합니다. 게이트웨이를 경유하는 다중 홉 SSH를 지원하여, 각 홉의 사용자명/비밀번호를 입력합니다.
  3. 백업 저장소 선택: 위에서 등록한 활성 저장소 중 하나를 선택해 Velero와 연결합니다.
  4. 설치 실행: Velero 네임스페이스 생성, CRD 설치, BackupStorageLocation 등록까지 자동으로 진행됩니다.

마법사 옵션 안내 — 가이드 이전 버전의 "버전 선택", "볼륨 스냅샷 활성화", "Provider", "Service Type" 같은 옵션은 현재 KIOPS UI에 존재하지 않습니다. 모두 기본값으로 자동 구성됩니다.

설치 상태 확인​

설치 진행과 결과는 저장소 관리 탭 하단의 InstallStatusDisplay 영역에서 확인할 수 있습니다.

  • Velero Pod 상태
  • BackupStorageLocation 상태
  • 연결된 외부 저장소 정보

kubectl로도 확인할 수 있습니다.

kubectl get pods -n velero
kubectl get backupstoragelocations -n velero

Velero 백업·복원 기능​

설치 이후 백업과 복원 과정에서 활용할 수 있는 주요 기능을 안내합니다.

백업 생성 옵션 (다중 네임스페이스 · PVC 데이터)​

Velero 백업은 백업 마법사로 생성합니다. 연결 방식(직접 SSH / VPN) → SSH 접속 정보 → 백업 설정 단계를 거치며, 마지막 백업 설정 모달에서 다음을 지정합니다.

  • 다중 네임스페이스 선택: 백업할 네임스페이스를 체크박스 목록에서 여러 개 선택합니다(전체 선택 토글 제공). 선택한 네임스페이스는 Velero --include-namespaces로 함께 백업됩니다.
  • 라벨 셀렉터(선택): 특정 라벨을 가진 리소스만 백업하도록 셀렉터를 입력할 수 있습니다.
  • PVC 데이터 포함(기본: 활성화): PersistentVolume 데이터까지 백업합니다(File System Backup). 해제 시 매니페스트(YAML)만 백업합니다.
  • 백업 저장소 선택: 인프라에 연결된 저장소 중 하나를 선택합니다.

리소스 종류 필터는 복구 시 선택 — PV/PVC 제외·앱 리소스만 등 리소스 종류 단위 필터는 백업 단계가 아니라 복구 단계의 리소스 복원 범위에서 선택합니다. 자세한 내용은 복구 가이드를 참고하세요.

백업 크기 자동 기록​

Velero 백업이 완료되면 KIOPS가 velero backup describe 출력의 Backup Size 값을 파싱하여 백업 크기를 자동으로 저장합니다. 별도 조회 없이 백업 목록에서 각 백업의 용량을 확인할 수 있어 스토리지 용량 계획에 활용할 수 있습니다.

복구 이력 세그먼트 분리​

K8s 복구 이력은 Velero와 컨트롤플레인 두 세그먼트로 나뉘어 표시됩니다. 백업 유형(backup_type)을 기준으로 분리되며, 복구 이력을 명확하게 구분해 확인할 수 있습니다. Velero 복구 이력에는 네임스페이스 필터가 추가로 제공되어 특정 네임스페이스의 복구 기록만 선택하여볼 수 있습니다.

네임스페이스 인식 복원​

복원 기록은 원본 백업과 연결됩니다. restores 테이블의 backup_id가 백업 레코드를 참조하므로, 각 복원 항목에서 원본 백업의 유형과 네임스페이스를 함께 확인할 수 있습니다. 이를 통해 어떤 백업으로부터 복원했는지 추적할 수 있습니다.

PVC 데이터 제외 복원​

백업에 PVC 볼륨 데이터가 포함된 경우, 복원 시 PVC 데이터 복원 옵션을 선택할 수 있습니다.

  • PVC 데이터 복원 (기본: 활성화): 백업된 PVC 볼륨 데이터를 함께 복원합니다.
  • 해제 시: 볼륨 데이터를 건너뛰고 K8s 리소스(Deployment, Service 등)만 복원합니다. 메타데이터·구성만 빠르게 복원하고 싶을 때 유용합니다.

옵션 표시 조건 — PVC 데이터 복원 옵션은 백업에 PVC 데이터가 포함된 경우에만 복원 모달에 표시됩니다.

문제 해결​

외부 저장소 연결 실패​

  • 연결 테스트 실패: 엔드포인트 URL, Access Key, Secret Key, 버킷명을 다시 확인하세요. 사내망에서 오브젝트 스토리지에 직접 접근할 수 없는 경우, 활성 VPN 세션을 사용하면 백업 작업의 SSH 실행이 자동으로 해당 터널을 경유합니다. 등록 모달에는 별도의 SSH 터널링 옵션이 없습니다.
  • 버킷 미존재: 오브젝트 스토리지에서 버킷을 먼저 생성한 뒤 등록을 다시 시도하세요.

Velero 설치 실패​

  • SSH 인증 실패: 마스터 노드 비밀번호가 올바른지 확인하세요.
  • CRD 설치 실패: 클러스터 관리자 권한을 가진 사용자로 시도했는지 확인하세요.
  • BackupStorageLocation이 Unavailable: 외부 저장소 인증 정보가 잘못되었거나, Velero Pod에서 오브젝트 스토리지 엔드포인트에 도달하지 못하는 경우입니다. 등록된 저장소 정보를 재검증하세요.

백업 실패​

  • PartiallyFailed: 일부 리소스의 백업이 실패했습니다. velero backup describe <backup-name> --details로 상세 로그를 확인하세요.
  • 스토리지 부족: 오브젝트 스토리지 버킷 용량이 가득 찼습니다. 오래된 백업을 정리하거나 저장 공간을 확장하세요.

오브젝트 스토리지 접근 확인​

등록한 외부 저장소의 엔드포인트와 자격증명으로 S3 호환 API가 정상 응답하는지 확인합니다. KIOPS 저장소 관리 탭의 연결 테스트 버튼을 활용하면 별도 CLI 없이 검증할 수 있습니다.

직접 확인하려면 awscli 또는 s3cmd 등 S3 호환 클라이언트를 사용하세요.

베스트 프랙티스​

스토리지 계획​

클러스터 규모에 따라 적절한 스토리지 용량을 확보하세요.

  • 소규모 (리소스 50개 미만): 일일 백업 크기 약 100MB, 30일 보존 시 50GB 권장
  • 중규모 (리소스 50~500개): 일일 백업 크기 약 1GB, 30일 보존 시 200GB 권장
  • 대규모 (리소스 500개 이상): 일일 백업 크기 약 10GB 이상, 30일 보존 시 1TB+ 권장

보안 권장사항​

백업 데이터 보안

백업 파일에는 Secret, ConfigMap 등 민감한 정보가 포함될 수 있습니다.

  1. 자격증명 관리: 오브젝트 스토리지 Access Key와 Secret Key를 안전한 비밀번호 관리자에 보관하세요.
  2. 네트워크 정책: NetworkPolicy 등으로 오브젝트 스토리지 접근 경로를 제한하세요.
  3. 복원 테스트: 정기적으로 복원 테스트를 수행하여 백업이 실제로 작동하는지 검증하세요.

다음 단계​

백업 인프라 설치가 완료되었습니다. 다음 가이드를 참고하여 백업과 복원을 수행하세요.