Disk Management Guide(KR) - cloud-barista/cb-spider GitHub Wiki

Disk Management Guide

Language: English | 한국어

1. CB-Spider Disk 개요

CB-Spider는 연동 대상 클라우드(CSP)가 제공하는 Disk(또는 Volume)를 동일한 인터페이스를 사용하여 제어할 수 있는 Disk 제어 기능을 제공한다.
CB-Spider 사용자는 Disk를 아래 그림과 같이 Root-Disk(R-Disk, 운영체제 포함)와 Data-Disk(D-Disk)로 활용할 수 있다.

[1. Root-Disk 활용]

(생성/부착) 사용자가 VM 생성 요청시 자동으로 Root-Disk가 생성되며,
- 생성된 VM에 생성된 Root-Disk가 부착(Attach) 되어 OS 운영에 필요한 시스템 디스크로 활용된다.
- 하나의 VM은 하나의 Root-Disk를 소유할 수 있다.
(해제/삭제) Root-Disk는 VM으로 부터 명시적인 해제(Detach)가 불가능하며,
- Disk를 소유한 VM 삭제 시에 자동으로 사용 해제(Detach) 되며 VM과 함께 삭제된다.
(타입/사이즈 설정) 사용자는 VM 생성 요청 시에 Root-Disk의 Disk Type과 Disk Size를 설정할 수 있다.
- 참고: VM Root Disk Configuration Guide

[2. Data-Disk 활용]

(생성) 사용자는 필요 시점에 Data-Disk를 생성할 수 있다.
(부착) 사용자는 생성한 Data-Disk를 운영 중인 특정 VM에 부착(Attach)하여 VM에서 활용할 수 있다.
- 또한, VM 생성시에 존재하는 Data-Disk를 부착할 수 있도록 설정할 수도 있다.
- 하나의 VM에 여러 개의 Data-Disk 부착이 가능하며, 하나의 Data-Disk는 하나의 VM에만 부착이 가능하다.
(해제) 사용자는 VM이 소유 중인 Data-Disk를 명시적으로 해제(Detach) 요청하여 회수할 수 있다.
- VM 삭제 시에는 대상 VM이 소유 중인 Data-Disk가 자동으로 소유 해제된다.
(삭제) 사용자는 더 이상 Data-Disk가 필요 없을 경우 Data-Disk를 삭제할 수 있다.

2. CB-Spider Disk 제공 기능

2.1 Disk 생성

Disk 생성 요청시 Disk 타입과 Size(단위:GB)의 설정이 가능하다.
Disk Type을 "default" 또는 ""(빈 문자열)로 지정 시 CSP의 기본 타입이 사용된다.
Disk Size를 "default" 또는 ""(빈 문자열)로 지정 시 CSP의 기본 크기가 사용된다.
※ CSP별 가능한 Disk Type 및 Size 값 참고
- cloudos_meta.yaml

2.2 Disk 목록 조회

Connection에 생성된 모든 Disk 목록을 조회할 수 있다.

2.3 Disk 정보 조회

특정 Disk의 타입, Size, 상태 및 소유 VM IID 정보 등을 제공한다.
제공하는 Disk 상태 종류는 다음과 같다.
- Creating: Disk가 생성 중인 상태
- Available: Disk가 VM에 부착 되지 않고 사용 가능한 상태
- Attached: Disk가 VM에 부착되어 특정 VM이 소유 중인 상태
  - Attached 상태일 때는 대상 Disk가 부착된 소유 VM IID 정보가 제공된다.
- Deleting: Disk가 삭제 중인 상태
- Error: Disk 오류 상태

2.4 Disk Size 증가

Disk Size 변경이 가능하며, 기존 보다 큰 크기로만 변경이 가능하다.
참고: AWS의 경우 수정 후에는 6시간이 경과해야 수정 가능하다.

2.5 Disk 부착

Available 상태인 Disk는 특정 VM에서 사용할 수 있도록 부착(Attach)이 가능하다.
부착된 Disk는 VM의 block device로 활용이 가능하며,
파일 시스템을 탑재하여 활용하고자 할 경우 포맷 및 마운트 과정이 필요하다.
- 참고: Format / Mount / UMount
하나의 VM에는 여러 개의 Disk 부착이 가능하며, 하나의 Disk는 하나의 VM에만 부착이 가능하다.

2.6 Disk 해제

특정 VM에 부착된 Disk를 해제(Detach)할 수 있다.
해제된 Disk는 다른 VM에 부착하여 활용할 수 있다.

2.7 Disk 삭제

사용하지 않는 Disk를 삭제할 수 있다.
Attached 상태인 Disk는 일반 삭제가 불가능하며, force 옵션을 사용하여 강제 삭제할 수 있다.

2.8 Disk 등록/해제

기존 CSP에 존재하는 Disk를 CB-Spider에 등록하여 관리할 수 있다.
등록된 Disk를 CB-Spider 관리에서 해제할 수 있다.

2.9 Disk 통계

전체 Disk 개수 또는 특정 Connection의 Disk 개수를 조회할 수 있다.

3. 참고: Format / Mount / UMount

VM에 부착된 Data-Disk를 VM에서 파일 저장 목적으로 활용하기 위해서는 파일 시스템 포맷과 마운트 과정이 필요하다.

3.1 부착된 Data-Disk 확인

$ lsblk
NAME    MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
loop0     7:0    0  44.7M  1 loop /snap/snapd/15534
loop1     7:1    0  55.5M  1 loop /snap/core18/2344
...
sda       8:0    0    10G  0 disk
|-sda1    8:1    0   9.9G  0 part /
|-sda14   8:14   0     4M  0 part
`-sda15   8:15   0   106M  0 part /boot/efi
sdc       8:16   0    18G  0 disk                   <=======

3.2 파일 시스템 포맷

Disk 속성 확인: 속성이 data일 경우 format 필요

$ sudo file -s /dev/sdc
/dev/sdc: data

Format 수행

$ sudo mkfs -t xfs /dev/sdc
meta-data=/dev/sdc               isize=512    agcount=4, agsize=1048576 blks
         =                       sectsz=4096  attr=2, projid32bit=1
         =                       crc=1        finobt=1, sparse=0, rmapbt=0, reflink=0
data     =                       bsize=4096   blocks=4194304, imaxpct=25
         =                       sunit=0      swidth=0 blks
naming   =version 2              bsize=4096   ascii-ci=0 ftype=1
log      =internal log           bsize=4096   blocks=2560, version=2
         =                       sectsz=4096  sunit=1 blks, lazy-count=1
realtime =none                   extsz=4096   blocks=0, rtextents=0

3.3 마운트

Disk 속성 확인

$ sudo file -s /dev/sdc
/dev/sdc: SGI XFS filesystem data (blksz 4096, inosz 512, v2 dirs)

Mount 수행

$ mkdir data
$ sudo mount /dev/sdc data
$ cd data
$ sudo chown cb-user:cb-user .

사용 예시

$ cd ~/data
$ vi input.dat

3.4 마운트 해제

Umount 수행

$ sudo umount -d /dev/sdc

4. CB-Spider Disk API 및 제공 정보 규격

사용자는 다음과 같은 CB-Spider REST API를 이용하여 Disk 정보를 JSON 규격으로 제공받는다.

4.1 Disk 관리 API

# Disk 생성 및 조회
POST   /spider/disk                     - Create Disk
GET    /spider/disk                     - List Disks
GET    /spider/disk/{Name}              - Get Disk
DELETE /spider/disk/{Name}              - Delete Disk

# Disk 등록/해제 (기존 CSP Disk 연동)
POST   /spider/regdisk                  - Register Disk
DELETE /spider/regdisk/{Name}           - Unregister Disk

# Disk Size 변경
PUT    /spider/disk/{Name}/size         - Increase Disk Size

# Disk 부착/해제
PUT    /spider/disk/{Name}/attach       - Attach Disk to VM
PUT    /spider/disk/{Name}/detach       - Detach Disk from VM

# Disk 목록 조회 (전체)
GET    /spider/alldisk                  - List All Disks (CB-Spider + CSP)
GET    /spider/alldiskinfo              - List All Disk Info

# Disk 통계
GET    /spider/countdisk                - Count All Disks
GET    /spider/countdisk/{ConnectionName} - Count Disks by Connection

# CSP Disk 직접 삭제
DELETE /spider/cspdisk/{Id}             - Delete CSP Disk

4.2 제공 정보 규격

Disk 정보 (DiskInfo)

필드	설명	예시
IId	Disk의 식별자 정보 (NameId, SystemId)	● {Name: "disk-01", SystemId: "vol-1234abcd"}
Zone	Disk가 위치한 가용 영역	● "us-east-1a", "ap-northeast-2a" 등
DiskType	Disk 타입	● "gp2", "gp3", "io1" 등
DiskSize	Disk 크기 (GB)	● "50", "100", "1000" 등
Status	Disk 상태	● "Creating", "Available", "Attached", "Deleting", "Error"
OwnerVM	Disk가 부착된 VM 정보 (Status가 Attached일 때만)	● {Name: "vm-01", SystemId: "i-5678efgh"}
CreatedTime	Disk 생성 시각	● "2024-01-15T10:30:00Z"
TagList	Disk에 할당된 태그 리스트	● [{Key: "Purpose", Value: "Database"}]
KeyValueList	CSP가 제공하는 추가 Disk 정보	● [{Key: "IOPS", Value: "3000"}]

5. CB-Spider Disk API 및 제공 정보 예시

5.1 Disk 생성 예시

Disk Type과 Size를 지정하여 Data-Disk를 생성하는 API 호출 예시:

curl -sX POST http://localhost:1024/spider/disk \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "disk-01",
      "Zone": "ap-southeast-2a",
      "DiskType": "gp3",
      "DiskSize": "100"
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "disk-01",
    "SystemId": "vol-0513e712757fc92a7"
  },
  "Zone": "ap-southeast-2a",
  "DiskType": "gp3",
  "DiskSize": "100",
  "Status": "Available",
  "OwnerVM": {
    "NameId": "",
    "SystemId": ""
  },
  "CreatedTime": "2026-02-04T13:47:45.153Z",
  "TagList": [
    {
      "Key": "Name",
      "Value": "disk-01-d61krvu1pc4njtmut8v0"
    }
  ],
  "KeyValueList": [
    {
      "Key": "AvailabilityZone",
      "Value": "ap-southeast-2a"
    },
    {
      "Key": "Encrypted",
      "Value": "false"
    },
    {
      "Key": "Iops",
      "Value": "3000"
    },
    {
      "Key": "State",
      "Value": "available"
    },
    {
      "Key": "Throughput",
      "Value": "125"
    },
    {
      "Key": "VolumeType",
      "Value": "gp3"
    }
  ]
}

5.2 Default 타입/크기로 Disk 생성 예시

DiskType과 DiskSize를 "default"로 지정하여 Disk 생성:

curl -sX POST http://localhost:1024/spider/disk \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "disk-02",
      "DiskType": "default",
      "DiskSize": "default"
    }
  }' | jq

5.3 Disk 조회 예시

생성된 Disk 정보를 조회하는 API 호출 예시:

curl -sX GET 'http://localhost:1024/spider/disk/disk-01?ConnectionName=aws-config01' | jq

응답 예시:

{
  "IId": {
    "NameId": "disk-01",
    "SystemId": "vol-0a1b2c3d4e5f67890"
  },
  "Zone": "us-east-1a",
  "DiskType": "gp3",
  "DiskSize": "100",
  "Status": "Available",
  "CreatedTime": "2024-01-15T10:30:00Z",
  "TagList": [],
  "KeyValueList": [
    {
      "Key": "IOPS",
      "Value": "3000"
    }
  ]
}

5.4 Disk 목록 조회 예시

Connection에 생성된 모든 Disk 목록을 조회하는 API 호출 예시:

curl -sX GET 'http://localhost:1024/spider/disk?ConnectionName=aws-config01' | jq

응답 예시:

{
  "disk": [
    {
      "IId": {
        "NameId": "disk-01",
        "SystemId": "vol-0a1b2c3d4e5f67890"
      },
      "Zone": "us-east-1a",
      "DiskType": "gp3",
      "DiskSize": "100",
      "Status": "Available",
      ...
    },
    {
      "IId": {
        "NameId": "vm-01-root",
        "SystemId": "vol-1b2c3d4e5f678901"
      },
      "Zone": "us-east-1a",
      "DiskType": "gp2",
      "DiskSize": "30",
      "Status": "Attached",
      "OwnerVM": {
        "NameId": "vm-01",
        "SystemId": "i-2c3d4e5f67890123"
      },
      ...
    }
  ]
}

5.5 Disk를 VM에 부착 예시

Available 상태의 Disk를 특정 VM에 부착하는 API 호출 예시:

curl -sX PUT http://localhost:1024/spider/disk/disk-01/attach \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "VMName": "vm-01"
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "disk-01",
    "SystemId": "vol-0a1b2c3d4e5f67890"
  },
  "Zone": "us-east-1a",
  "DiskType": "gp3",
  "DiskSize": "100",
  "Status": "Attached",
  "OwnerVM": {
    "NameId": "vm-01",
    "SystemId": "i-2c3d4e5f67890123"
  },
  "CreatedTime": "2024-01-15T10:30:00Z",
  ...
}

5.6 Disk를 VM에서 해제 예시

VM에 부착된 Disk를 해제하는 API 호출 예시:

curl -sX PUT http://localhost:1024/spider/disk/disk-01/detach \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "VMName": "vm-01"
    }
  }' | jq

응답 예시:

{
  "Result": "true"
}

5.7 Disk Size 증가 예시

기존 Disk의 Size를 증가시키는 API 호출 예시:

curl -sX PUT http://localhost:1024/spider/disk/disk-01/size \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Size": "200"
    }
  }' | jq

응답 예시:

{
  "Result": "true"
}

5.8 Disk 삭제 예시

Disk를 삭제하는 API 호출 예시:

curl -sX DELETE 'http://localhost:1024/spider/disk/disk-01' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

응답 예시:

{
  "Result": "true"
}

5.9 강제 삭제 예시

Disk를 강제로 삭제하는 API 호출 예시 (VM에 부착되어 있어도 삭제):

curl -sX DELETE 'http://localhost:1024/spider/disk/disk-01?force=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

6. CB-Spider Disk AdminWeb 활용 예시

AdminWeb을 통한 Disk 관리 절차는 다음과 같다:
1. Connection 선택: AdminWeb 상단에서 대상 CSP Connection 선택
2. Disk 메뉴 접근: 좌측 메뉴에서 "Disk" 선택
3. Disk 생성: "Create Disk" 버튼 클릭 후 필요한 정보 입력
4. Disk 관리: Disk 상태 확인, 부착/해제, Size 변경, 삭제 등

6.1 Disk 목록 화면 예시

AdminWeb에서 Disk 목록을 조회할 때 다음 정보가 표시된다:

Disk 이름
Zone
Disk Type
Disk Size (GB)
Status (Creating, Available, Attached, Deleting, Error)
Owner VM (Attached 상태인 경우)
작업 버튼 (상세보기, 부착, 해제, Size 변경, 삭제 등)

6.2 Disk 생성 화면 예시

AdminWeb에서 Disk를 생성할 때 다음 정보를 입력한다:

Disk Name: CB-Spider에서 관리할 Disk 이름
Zone: Disk를 생성할 가용 영역 (선택적, 미지정 시 Connection의 기본 Zone 사용)
Disk Type: Disk 타입 선택 또는 "default" 입력
- 예시: gp2, gp3, io1, io2 (AWS), Premium_LRS, Standard_LRS (Azure) 등
Disk Size: Disk 크기 (GB) 또는 "default" 입력
- 예시: 50, 100, 500, 1000 등
Tags (선택적): 리소스 태그 정보

6.3 Disk 상세 정보 화면 예시

Disk 상세 정보 화면에서는 다음 정보가 표시된다:

기본 정보:

Disk IId (NameId, SystemId)
Zone
Disk Type
Disk Size (GB)
Status
Created Time

소유 VM 정보 (Attached 상태인 경우):

Owner VM IId (NameId, SystemId)

작업 버튼:

Attach to VM (Available 상태인 경우)
Detach from VM (Attached 상태인 경우)
Increase Size
Delete Disk

7. 주의사항 및 제약사항

7.1 Disk 생성 시 주의사항

Zone 지정: Disk를 VM에 부착하려면 동일한 Zone에 있어야 함
Disk Type: CSP별로 지원하는 Disk Type이 다르므로 사전 확인 필요
Disk Size: CSP별로 최소/최대 Size 제한이 있음
Default 값: DiskType 또는 DiskSize를 "default" 또는 ""(빈 문자열)로 지정 시 CSP의 기본값 사용

7.2 Disk 부착 시 주의사항

Zone 일치: Disk와 VM이 동일한 Zone에 있어야 부착 가능
Available 상태: Disk가 Available 상태여야 부착 가능
부착 제한: 하나의 Disk는 하나의 VM에만 부착 가능
포맷/마운트: 부착 후 VM에서 파일 시스템 사용을 위해 포맷 및 마운트 필요
- 참고: Format / Mount / UMount

7.3 Disk Size 변경 시 주의사항

증가만 가능: 현재 크기보다 큰 크기로만 변경 가능 (감소 불가)
변경 제한: CSP별로 Size 변경 주기 제한이 있음
- 예: AWS는 6시간 경과 후 재변경 가능
파일 시스템 확장: Size 증가 후 VM에서 파일 시스템 확장 작업 필요

7.4 Disk 삭제 시 주의사항

Attached 상태: Attached 상태인 Disk는 일반 삭제 불가 (force 옵션 사용 시 가능)
강제 삭제: force=true 옵션 사용 시 연결된 리소스 검증 없이 강제 삭제됨 (주의!)
Root-Disk: VM의 Root-Disk는 VM 삭제 시 자동으로 삭제됨

Disk Management Guide(KR) - cloud-barista/cb-spider GitHub Wiki

Disk Management Guide

1. CB-Spider Disk 개요

[1. Root-Disk 활용]

[2. Data-Disk 활용]

2. CB-Spider Disk 제공 기능

2.1 Disk 생성

2.2 Disk 목록 조회

2.3 Disk 정보 조회

2.4 Disk Size 증가

2.5 Disk 부착

2.6 Disk 해제

2.7 Disk 삭제

2.8 Disk 등록/해제

2.9 Disk 통계

3. 참고: Format / Mount / UMount

3.1 부착된 Data-Disk 확인

3.2 파일 시스템 포맷

3.3 마운트

3.4 마운트 해제

4. CB-Spider Disk API 및 제공 정보 규격

4.1 Disk 관리 API

4.2 제공 정보 규격

5. CB-Spider Disk API 및 제공 정보 예시

5.1 Disk 생성 예시

5.2 Default 타입/크기로 Disk 생성 예시

5.3 Disk 조회 예시

5.4 Disk 목록 조회 예시

5.5 Disk를 VM에 부착 예시

5.6 Disk를 VM에서 해제 예시

5.7 Disk Size 증가 예시

5.8 Disk 삭제 예시

5.9 강제 삭제 예시

6. CB-Spider Disk AdminWeb 활용 예시

6.1 Disk 목록 화면 예시

6.2 Disk 생성 화면 예시

6.3 Disk 상세 정보 화면 예시

7. 주의사항 및 제약사항

7.1 Disk 생성 시 주의사항

7.2 Disk 부착 시 주의사항

7.3 Disk Size 변경 시 주의사항

7.4 Disk 삭제 시 주의사항

8. 참고 자료