Skip to content

VM Management Guide

Jump to bottom Edit New page
ByoungSeob Kim edited this page Feb 4, 2026 · 1 revision

VM Management Guide

Language: English | 한국어

1. CB-Spider VM Overview

  • Users can manage Virtual Machines (VMs) across multi-cloud environments through CB-Spider.
  • VMs are configured with network resources such as VPC, Subnet, Security Group, and KeyPair to form complete cloud infrastructure.
  • CB-Spider provides APIs to manage the entire VM lifecycle (create/start, suspend, resume, reboot, terminate).
  • The relationship between VMs and related resources is shown in the diagram below.
┌─────────────────────────────────────────────────────────────┐
│                     CB-Spider VM                            │
│                                                             │
│  VPC (10.0.0.0/16)                                          │
│  ├── SecurityGroup-1 (SSH, HTTP, HTTPS)                     │
│  ├── Subnet-1 (10.0.0.0/24, us-east-1a)                     │
│  │   └── VM-1                                               │
│  │       ├── Image: Ubuntu 22.04                            │
│  │       ├── Spec: t2.micro                                 │
│  │       ├── KeyPair: keypair-01                            │
│  │       ├── PublicIP: 1.2.3.4                              │
│  │       ├── PrivateIP: 10.0.0.10                           │
│  │       ├── RootDisk: 30GB (gp2)                           │
│  │       └── DataDisks: disk-01, disk-02                    │
│  └── Subnet-2 (10.0.1.0/24, us-east-1b)                     │
│      └── VM-2, VM-3, ...                                    │
└─────────────────────────────────────────────────────────────┘

2. CB-Spider VM API and Information Specification

2.1 VM Lifecycle Management API

# VM Creation/Start and Query
POST   /spider/vm                       - Start VM (Create and start VM)
GET    /spider/vm                       - List VMs
GET    /spider/vm/{Name}                - Get VM
DELETE /spider/vm/{Name}                - Terminate VM

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

# VM List Query (All)
GET    /spider/allvm                    - List All VMs (CB-Spider + CSP)
GET    /spider/allvminfo                - List All VMs Info

# VM Status Management
GET    /spider/vmstatus                 - List VM Statuses
GET    /spider/vmstatus/{Name}          - Get VM Status
PUT    /spider/controlvm/{Name}?action={suspend|resume|reboot} - Control VM

# VM Statistics
GET    /spider/countvm                  - Count All VMs
GET    /spider/countvm/{ConnectionName} - Count VMs by Connection

# Direct CSP VM Query/Deletion
GET    /spider/cspvm/{Id}               - Get CSP VM
DELETE /spider/cspvm/{Id}               - Terminate CSP VM

# VM Using Resources Query
POST   /spider/getvmusingresources      - Get VM Using Resources

2.2 Information Specification

VM Information (VMInfo)

Field Description Examples
IId VM identifier information (NameId, SystemId) ● {Name: "vm-01", SystemId: "i-1234abcd"}
StartTime VM start time ● "2024-08-27T10:00:00Z"
Region Region and Zone information where VM is located ● {Region: "us-east-1", Zone: "us-east-1a"}
ImageType Image type ● "PublicImage" or "MyImage"
ImageIId VM image information ● {Name: "ubuntu-22.04", SystemId: "ami-1234"}
VMSpecName VM specification name ● "t2.micro", "Standard_B2s", etc.
VpcIID VPC identifier ● {Name: "vpc-01", SystemId: "vpc-1234"}
SubnetIID Subnet identifier ● {Name: "subnet-01", SystemId: "subnet-1234"}
SecurityGroupIIds Security group list ● [{Name: "sg-01", SystemId: "sg-1234"}]
KeyPairIId KeyPair information ● {Name: "keypair-01", SystemId: "key-1234"}
RootDiskType Root disk type ● "gp2", "Premium SSD", etc.
RootDiskSize Root disk size (GB) ● "30", "100", etc.
RootDeviceName Root device name ● "/dev/sda1"
DataDiskIIDs Data disk list ● [{Name: "disk-01", SystemId: "vol-1234"}]
VMUserId VM access user ID ● "cb-user" (CB-Spider abstracted user)
VMUserPasswd VM user password (Windows only) ● "password1234"
NetworkInterface Network interface ● "eni-12345678"
PublicIP Public IP address ● "1.2.3.4"
PublicDNS Public DNS name ● "ec2-1-2-3-4.compute-1.amazonaws.com"
PrivateIP Private IP address ● "10.0.0.10"
PrivateDNS Private DNS name ● "ip-10-0-0-10.ec2.internal"
Platform Platform type ● "LINUX/UNIX" or "WINDOWS"
AccessPoint SSH/RDP access point ● "1.2.3.4:22" (Linux), "1.2.3.4:3389" (Windows)
TagList List of tags assigned to VM ● [{Key: "Name", Value: "MyVM"}]
KeyValueList Additional information provided by CSP ● [{Key: "Architecture", Value: "x86_64"}]

VM Status Information (VMStatus)

Status Description
Creating VM is being created
Running VM is running
Suspending VM is being suspended
Suspended VM is suspended
Resuming VM is being resumed
Rebooting VM is rebooting
Terminating VM is being terminated
Terminated VM is terminated
NotExist VM does not exist
Failed VM is in error state

Key Field Descriptions:

  • ImageType: PublicImage (public image) or MyImage (user snapshot image)
  • VMUserId: Always uses "cb-user" abstracted user in CB-Spider
  • Platform: LINUX/UNIX or WINDOWS
  • AccessPoint: SSH (Linux) or RDP (Windows) access point

3. CB-Spider VM API and Information Examples

3.1 VM Creation Example (Linux)

  • API call and result example for creating an Ubuntu VM in AWS:
curl -sX 'POST' 'http://localhost:1024/spider/vm' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "vm-web-01",
      "ImageType": "PublicImage",
      "ImageName": "ami-009e2f5f8d69abd47",
      "VMSpecName": "t2.micro",
      "VPCName": "vpc-01",
      "SubnetName": "subnet-01",
      "SecurityGroupNames": ["sg-web", "sg-ssh"],
      "KeyPairName": "keypair-web",
      "RootDiskType": "gp2",
      "RootDiskSize": "30"
    }
  }' | jq

Response Example:

{
  "IId": {
    "NameId": "vm-web-01",
    "SystemId": "i-0a1b2c3d4e5f67890"
  },
  "StartTime": "2024-08-27T10:30:00Z",
  "Region": {
    "Region": "us-east-1",
    "Zone": "us-east-1a"
  },
  "ImageType": "PublicImage",
  "ImageIId": {
    "NameId": "ami-009e2f5f8d69abd47",
    "SystemId": "ami-009e2f5f8d69abd47"
  },
  "VMSpecName": "t2.micro",
  "VpcIID": {
    "NameId": "vpc-01",
    "SystemId": "vpc-0a1b2c3d"
  },
  "SubnetIID": {
    "NameId": "subnet-01",
    "SystemId": "subnet-1a2b3c4d"
  },
  "SecurityGroupIIds": [
    {
      "NameId": "sg-web",
      "SystemId": "sg-0a1b2c3d"
    },
    {
      "NameId": "sg-ssh",
      "SystemId": "sg-1b2c3d4e"
    }
  ],
  "KeyPairIId": {
    "NameId": "keypair-web",
    "SystemId": "keypair-web-d60mdhu1pc4mliscb9og"
  },
  "RootDiskType": "gp2",
  "RootDiskSize": "30",
  "RootDeviceName": "/dev/sda1",
  "VMUserId": "cb-user",
  "NetworkInterface": "eni-0a1b2c3d4e5f67890",
  "PublicIP": "54.123.45.67",
  "PublicDNS": "ec2-54-123-45-67.compute-1.amazonaws.com",
  "PrivateIP": "10.0.0.10",
  "PrivateDNS": "ip-10-0-0-10.ec2.internal",
  "Platform": "LINUX/UNIX",
  "SSHAccessPoint": "54.123.45.67:22",
  "AccessPoint": "",
  "KeyValueList": [
    {
      "Key": "Architecture",
      "Value": "x86_64"
    },
    {
      "Key": "InstanceState",
      "Value": "running"
    }
  ]
}

3.2 VM Creation Example (Windows)

  • Specify VMUserId and VMUserPasswd when creating Windows VM:
curl -sX 'POST' 'http://localhost:1024/spider/vm' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "vm-windows-01",
      "ImageType": "PublicImage",
      "ImageName": "windows-server-2022",
      "VMSpecName": "t3.medium",
      "VPCName": "vpc-01",
      "SubnetName": "subnet-01",
      "SecurityGroupNames": ["sg-rdp"],
      "KeyPairName": "keypair-windows",
      "VMUserId": "Administrator",
      "VMUserPasswd": "SecureP@ssw0rd!",
      "RootDiskType": "gp2",
      "RootDiskSize": "50"
    }
  }' | jq

3.3 VM Creation with Data Disks Example

curl -sX 'POST' 'http://localhost:1024/spider/vm' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "vm-data-01",
      "ImageType": "PublicImage",
      "ImageName": "ubuntu-22.04-server",
      "VMSpecName": "t2.medium",
      "VPCName": "vpc-01",
      "SubnetName": "subnet-01",
      "SecurityGroupNames": ["sg-web"],
      "KeyPairName": "keypair-web",
      "RootDiskSize": "30",
      "DataDiskNames": ["data-disk-01", "data-disk-02"]
    }
  }' | jq

3.4 VM List Query Example

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

Response Example:

{
  "vm": [
    {
      "IId": {
        "NameId": "vm-web-01",
        "SystemId": "i-0a1b2c3d4e5f67890"
      },
      "PublicIP": "54.123.45.67",
      "PrivateIP": "10.0.0.10",
      "VMSpecName": "t2.micro",
      "Platform": "LINUX/UNIX",
      ...
    },
    {
      "IId": {
        "NameId": "vm-web-02",
        "SystemId": "i-1b2c3d4e5f678901"
      },
      "PublicIP": "54.123.45.68",
      "PrivateIP": "10.0.0.11",
      "VMSpecName": "t2.micro",
      "Platform": "LINUX/UNIX",
      ...
    }
  ]
}

3.5 VM Status Query Example

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

Response Example:

{
  "Status": "Running"
}

3.6 VM Control Examples

VM Suspend:

curl -sX 'PUT' 'http://localhost:1024/spider/controlvm/vm-web-01?action=suspend' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

VM Resume:

curl -sX 'PUT' 'http://localhost:1024/spider/controlvm/vm-web-01?action=resume' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

VM Reboot:

curl -sX 'PUT' 'http://localhost:1024/spider/controlvm/vm-web-01?action=reboot' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

Response Example:

{
  "Status": "Suspended"
}

3.7 VM Termination Example

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

Response Example:

{
  "Status": "Terminated"
}

3.8 Force Termination Example

  • Force terminate VM even if there are connected resources:
curl -sX 'DELETE' 'http://localhost:1024/spider/vm/vm-web-01?force=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

4. CB-Spider VM AdminWeb Examples

  • Follow these steps to select the target CSP and manage VM information:

    1. Select Connection: Choose the target CSP Connection from the top of AdminWeb
    2. Access VM Menu: Select "VM" from the left menu
    3. Create VM: Click "Start VM" button and enter required information
    4. Manage VM: Check VM status, control, terminate, etc.

4.1 VM List Screen Example

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

  • VM Name
  • VM Status (Running, Suspended, etc.)
  • Public IP / Private IP
  • VM Spec
  • Platform (LINUX/UNIX, WINDOWS)
  • Creation Time
  • Action Buttons (Details, Control, Terminate, etc.)

4.2 VM Creation Screen Example

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

  • VM Name: VM name to be managed in CB-Spider
  • Image Type: PublicImage or MyImage
  • Image Name: Select image to use
  • VM Spec: Select instance type
  • VPC/Subnet: Select network configuration
  • Security Groups: Select security groups (multiple selection possible)
  • KeyPair: Select keypair for SSH access
  • Root Disk: Specify disk type and size
  • Data Disks (optional): Select additional data disks
  • Tags (optional): Resource tag information

4.3 VM Details Screen Example

The VM details screen displays the following information:

Basic Information:

  • VM IId (NameId, SystemId)
  • VM Status
  • Start Time
  • Region/Zone

Network Information:

  • VPC/Subnet
  • Security Groups
  • Public IP/DNS
  • Private IP/DNS
  • Network Interface

Specification and Disks:

  • VM Spec Name
  • Image Information
  • Root Disk (Type, Size, Device Name)
  • Data Disks (if any)

Access Information:

  • Platform (LINUX/UNIX or WINDOWS)
  • VM User ID
  • Access Point (IP:Port)
  • KeyPair Information

Action Buttons:

  • Control VM: Suspend, Resume, Reboot
  • Terminate VM: Terminate VM
  • Refresh: Refresh information

5. VM Lifecycle Management

5.1 VM Lifecycle State Transition Diagram

stateDiagram-v2
    [*] --> Creating: StartVM
    Creating --> Running: Creation Complete
    
    Running --> Suspending: Suspend
    Suspending --> Suspended: Suspension Complete
    Suspended --> Resuming: Resume
    Resuming --> Running: Resume Complete
    
    Running --> Rebooting: Reboot
    Rebooting --> Running: Reboot Complete
    
    Running --> Terminating: Terminate
    Suspended --> Terminating: Terminate
    Terminating --> Terminated: Termination Complete
    Terminated --> [*]
    
    Creating --> Failed: Error
    Running --> Failed: Error
    Suspending --> Failed: Error
    Resuming --> Failed: Error
    Rebooting --> Failed: Error
    Terminating --> Failed: Error
Loading

5.2 Possible Actions by VM State

Current State Possible Actions
Creating Wait (until creation completes)
Running Suspend, Reboot, Terminate
Suspending Wait (until suspension completes)
Suspended Resume, Terminate
Resuming Wait (until resumption completes)
Rebooting Wait (until reboot completes)
Terminating Wait (until termination completes)
Terminated Deleted

6. Precautions and Limitations

6.1 VM Creation Precautions

  • Pre-create Required Resources: VPC, Subnet, Security Group, KeyPair must be created before VM creation
  • Zone Matching: Subnet and DataDisks must be in the same Zone
  • Image Type Selection: Choose between PublicImage (public image) or MyImage (snapshot image)
  • Windows VM: VMUserId and VMUserPasswd are required
  • Root Disk Size: Check CSP-specific minimum/maximum size constraints

6.2 VM Termination Precautions

  • Data Backup: Root Disk data is deleted when VM is terminated, so backup necessary data beforehand
  • Force Termination: Using force=true option forcefully terminates without validating relationships with connected resources (caution!)

6.3 VM Access

  • Linux VM: SSH access - ssh -i keypair.pem cb-user@<Public-IP>
  • Windows VM: RDP access - Connect via Windows Remote Desktop to <Public-IP>:3389
  • VMUserId: CB-Spider automatically creates "cb-user" account on all VMs (abstracted user)
  • KeyPair: Required for Linux VM access, keep Private Key secure

7. References

Add a custom footer

Table of contents

Clone this wiki locally