Disk Management Guide - cloud-barista/cb-spider GitHub Wiki

Disk Management Guide

Language: English | 한국어

1. CB-Spider Disk Overview

CB-Spider provides Disk (or Volume) control functionality that allows users to control Disks provided by connected Cloud Service Providers (CSPs) using a unified interface.
CB-Spider users can utilize Disks as Root-Disk (R-Disk, including operating system) and Data-Disk (D-Disk) as shown in the diagram below.

[1. Root-Disk Usage]

(Creation/Attachment) When a user requests VM creation, a Root-Disk is automatically created,
- The created Root-Disk is attached to the created VM and utilized as a system disk necessary for OS operation.
- One VM can own one Root-Disk.
(Detachment/Deletion) Root-Disk cannot be explicitly detached from the VM,
- When the VM that owns the Disk is deleted, it is automatically detached and deleted together with the VM.
(Type/Size Configuration) Users can configure the Disk Type and Disk Size of the Root-Disk when requesting VM creation.
- Reference: VM Root Disk Configuration Guide

[2. Data-Disk Usage]

(Creation) Users can create Data-Disks at any time as needed.
(Attachment) Users can attach created Data-Disks to specific running VMs for utilization.
- Additionally, existing Data-Disks can be configured to be attached during VM creation.
- Multiple Data-Disks can be attached to one VM, and one Data-Disk can only be attached to one VM.
(Detachment) Users can explicitly request to detach Data-Disks owned by a VM to reclaim them.
- When a VM is deleted, Data-Disks owned by the target VM are automatically detached.
(Deletion) Users can delete Data-Disks when they are no longer needed.

2. CB-Spider Disk Features

2.1 Disk Creation

When requesting Disk creation, Disk type and Size (unit: GB) can be configured.
When Disk Type is specified as "default" or "" (empty string), the CSP's default type is used.
When Disk Size is specified as "default" or "" (empty string), the CSP's default size is used.
Reference for CSP-specific available Disk Type and Size values
- cloudos_meta.yaml

2.2 Disk List Query

Users can query a list of all Disks created in a Connection.

2.3 Disk Information Query

Provides information such as type, Size, status, and owner VM IID of a specific Disk.
The types of Disk statuses provided are as follows:
- Creating: Disk is being created
- Available: Disk is not attached to a VM and is available for use
- Attached: Disk is attached to a VM and owned by a specific VM
  - When in Attached status, information about the owner VM IID to which the target Disk is attached is provided.
- Deleting: Disk is being deleted
- Error: Disk error status

2.4 Disk Size Increase

Disk Size can be modified, and can only be changed to a larger size than the current size.
Note: For AWS, modification is only possible after 6 hours have elapsed since the last modification.

2.5 Disk Attachment

Disks in Available status can be attached to specific VMs for use.
Attached Disks can be utilized as block devices of the VM,
If you want to mount a file system for utilization, formatting and mounting processes are required.
- Reference: Format / Mount / Umount
Multiple Disks can be attached to one VM, and one Disk can only be attached to one VM.

2.6 Disk Detachment

Disks attached to specific VMs can be detached.
Detached Disks can be attached to other VMs for utilization.

2.7 Disk Deletion

Unused Disks can be deleted.
Disks in Attached status cannot be deleted normally, but can be forcefully deleted using the force option.

2.8 Disk Registration/Unregistration

Existing Disks in CSP can be registered and managed in CB-Spider.
Registered Disks can be unregistered from CB-Spider management.

2.9 Disk Statistics

Users can query the total number of Disks or the number of Disks for a specific Connection.

3. Reference: Format / Mount / Umount

To utilize Data-Disks attached to VMs for file storage purposes within the VM, file system formatting and mounting processes are required.

3.1 Check Attached 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 File System Format

Check Disk Properties: If the property is data, formatting is required

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

Perform 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 Mount

Check Disk Properties

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

Perform Mount

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

Usage Example

$ cd ~/data
$ vi input.dat

3.4 Unmount

Perform Umount

$ sudo umount -d /dev/sdc

4. CB-Spider Disk API and Information Specification

Users can receive Disk information in JSON format using the following CB-Spider REST API.

4.1 Disk Management API

# Disk Creation and Query
POST   /spider/disk                     - Create Disk
GET    /spider/disk                     - List Disks
GET    /spider/disk/{Name}              - Get Disk
DELETE /spider/disk/{Name}              - Delete Disk

# Disk Registration/Unregistration (Integration with existing CSP Disk)
POST   /spider/regdisk                  - Register Disk
DELETE /spider/regdisk/{Name}           - Unregister Disk

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

# Disk Attachment/Detachment
PUT    /spider/disk/{Name}/attach       - Attach Disk to VM
PUT    /spider/disk/{Name}/detach       - Detach Disk from VM

# Disk List Query (All)
GET    /spider/alldisk                  - List All Disks (CB-Spider + CSP)
GET    /spider/alldiskinfo              - List All Disk Info

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

# Direct CSP Disk Deletion
DELETE /spider/cspdisk/{Id}             - Delete CSP Disk

4.2 Information Specification

Disk Information (DiskInfo)

Field	Description	Examples
IId	Disk identifier information (NameId, SystemId)	● {Name: "disk-01", SystemId: "vol-1234abcd"}
Zone	Availability Zone where the Disk is located	● "us-east-1a", "ap-northeast-2a", etc.
DiskType	Disk type	● "gp2", "gp3", "io1" etc.
DiskSize	Disk size (GB)	● "50", "100", "1000" etc.
Status	Disk status	● "Creating", "Available", "Attached", "Deleting", "Error"
OwnerVM	VM information to which the Disk is attached (only when Status is Attached)	● {Name: "vm-01", SystemId: "i-5678efgh"}
CreatedTime	Disk creation time	● "2024-01-15T10:30:00Z"
TagList	List of tags assigned to the Disk	● [{Key: "Purpose", Value: "Database"}]
KeyValueList	Additional Disk information provided by CSP	● [{Key: "IOPS", Value: "3000"}]

5. CB-Spider Disk API and Information Examples

5.1 Disk Creation Example

API call example for creating a Data-Disk with specified Disk Type and Size:

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

Response Example:

{
  "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 Disk Creation with Default Type/Size Example

Creating a Disk with DiskType and DiskSize specified as "default":

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 Query Example

API call example for querying created Disk information:

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

Response Example:

{
  "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 List Query Example

API call example for querying all Disk lists created in a Connection:

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

Response Example:

{
  "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 Attach Disk to VM Example

API call example for attaching an Available Disk to a specific VM:

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

Response Example:

{
  "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 Detach Disk from VM Example

API call example for detaching a Disk attached to a VM:

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

Response Example:

{
  "Result": "true"
}

5.7 Increase Disk Size Example

API call example for increasing the Size of an existing Disk:

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

Response Example:

{
  "Result": "true"
}

5.8 Disk Deletion Example

API call example for deleting a Disk:

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

Response Example:

{
  "Result": "true"
}

5.9 Force Deletion Example

API call example for forcefully deleting a Disk (deletes even if attached to a 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 Usage Examples

The Disk management procedure through AdminWeb is as follows:
1. Select Connection: Select target CSP Connection from the top of AdminWeb
2. Access Disk Menu: Select "Disk" from the left menu
3. Create Disk: Click "Create Disk" button and enter required information
4. Manage Disk: Check Disk status, attach/detach, modify Size, delete, etc.

6.1 Disk List Screen Example

When viewing the Disk list in AdminWeb, the following information is displayed:

Disk Name
Zone
Disk Type
Disk Size (GB)
Status (Creating, Available, Attached, Deleting, Error)
Owner VM (if in Attached status)
Action Buttons (Details, Attach, Detach, Modify Size, Delete, etc.)

6.2 Disk Creation Screen Example

When creating a Disk in AdminWeb, enter the following information:

Disk Name: Disk name to be managed in CB-Spider
Zone: Availability zone to create the Disk (optional, uses Connection's default Zone if not specified)
Disk Type: Select Disk type or enter "default"
- Examples: gp2, gp3, io1, io2 (AWS), Premium_LRS, Standard_LRS (Azure), etc.
Disk Size: Disk size (GB) or enter "default"
- Examples: 50, 100, 500, 1000, etc.
Tags (optional): Resource tag information

6.3 Disk Details Screen Example

The Disk details screen displays the following information:

Basic Information:

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

Owner VM Information (if in Attached status):

Owner VM IId (NameId, SystemId)

Action Buttons:

Attach to VM (if in Available status)
Detach from VM (if in Attached status)
Increase Size
Delete Disk

7. Precautions and Limitations

7.1 Disk Creation Precautions

Zone Specification: Disk must be in the same Zone as the VM to be attached
Disk Type: Check CSP-supported Disk Types in advance as they differ by CSP
Disk Size: CSPs have minimum/maximum Size limitations
Default Values: When DiskType or DiskSize is specified as "default" or "" (empty string), CSP's default values are used

7.2 Disk Attachment Precautions

Zone Match: Disk and VM must be in the same Zone for attachment
Available Status: Disk must be in Available status for attachment
Attachment Limit: One Disk can only be attached to one VM
Format/Mount: After attachment, formatting and mounting are required for file system usage in the VM
- Reference: Format / Mount / Umount

7.3 Disk Size Modification Precautions

Increase Only: Can only be changed to a larger size than the current size (decrease not possible)
Modification Limit: CSPs have limitations on the frequency of Size modifications
- Example: AWS allows re-modification only after 6 hours have elapsed
File System Expansion: After Size increase, file system expansion work is required in the VM

7.4 Disk Deletion Precautions

Attached Status: Disks in Attached status cannot be deleted normally (possible with force option)
Force Deletion: Using force=true option forcefully deletes without validating relationships with connected resources (caution!)
Root-Disk: VM's Root-Disk is automatically deleted when the VM is deleted

Disk Management Guide - cloud-barista/cb-spider GitHub Wiki

Disk Management Guide

1. CB-Spider Disk Overview

[1. Root-Disk Usage]

[2. Data-Disk Usage]

2. CB-Spider Disk Features

2.1 Disk Creation

2.2 Disk List Query

2.3 Disk Information Query

2.4 Disk Size Increase

2.5 Disk Attachment

2.6 Disk Detachment

2.7 Disk Deletion

2.8 Disk Registration/Unregistration

2.9 Disk Statistics

3. Reference: Format / Mount / Umount

3.1 Check Attached Data-Disk

3.2 File System Format

3.3 Mount

3.4 Unmount

4. CB-Spider Disk API and Information Specification

4.1 Disk Management API

4.2 Information Specification

5. CB-Spider Disk API and Information Examples

5.1 Disk Creation Example

5.2 Disk Creation with Default Type/Size Example

5.3 Disk Query Example

5.4 Disk List Query Example

5.5 Attach Disk to VM Example

5.6 Detach Disk from VM Example

5.7 Increase Disk Size Example

5.8 Disk Deletion Example

5.9 Force Deletion Example

6. CB-Spider Disk AdminWeb Usage Examples

6.1 Disk List Screen Example

6.2 Disk Creation Screen Example

6.3 Disk Details Screen Example

7. Precautions and Limitations

7.1 Disk Creation Precautions

7.2 Disk Attachment Precautions

7.3 Disk Size Modification Precautions

7.4 Disk Deletion Precautions

8. References