VM Management Guide

Language: English | 한국어

1. CB-Spider VM 개요

사용자는 CB-Spider를 통해 멀티 클라우드 환경에서 가상머신(VM)을 통합 관리할 수 있다.
VM은 VPC, Subnet, Security Group, KeyPair 등의 네트워크 리소스와 함께 구성되어 완전한 클라우드 인프라를 형성한다.
CB-Spider는 VM 생명주기(생성/시작, 중지, 재개, 재부팅, 종료) 전반을 관리하는 API를 제공한다.
VM과 관련 리소스 간의 관계는 아래 그림과 같다.

┌─────────────────────────────────────────────────────────────┐
│                     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 및 제공 정보 규격

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

2.1 VM 생명주기 관리 API

# VM 생성/시작 및 조회
POST   /spider/vm                       - Start VM (VM 생성 및 시작)
GET    /spider/vm                       - List VMs
GET    /spider/vm/{Name}                - Get VM
DELETE /spider/vm/{Name}                - Terminate VM

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

# VM 목록 조회 (전체)
GET    /spider/allvm                    - List All VMs (CB-Spider + CSP)
GET    /spider/allvminfo                - List All VMs Info

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

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

# CSP VM 직접 조회/삭제
GET    /spider/cspvm/{Id}               - Get CSP VM
DELETE /spider/cspvm/{Id}               - Terminate CSP VM

# VM 사용 리소스 조회
POST   /spider/getvmusingresources      - Get VM Using Resources

2.2 제공 정보 규격

VM 정보 (VMInfo)

필드	설명	예시
IId	VM 식별자 정보 (NameId, SystemId)	● {Name: "vm-01", SystemId: "i-1234abcd"}
StartTime	VM 시작 시간	● "2024-08-27T10:00:00Z"
Region	VM이 위치한 리전 및 Zone 정보	● {Region: "us-east-1", Zone: "us-east-1a"}
ImageType	이미지 타입	● "PublicImage" 또는 "MyImage"
ImageIId	VM 이미지 정보	● {Name: "ubuntu-22.04", SystemId: "ami-1234"}
VMSpecName	VM 사양 이름	● "t2.micro", "Standard_B2s" 등
VpcIID	VPC 식별자	● {Name: "vpc-01", SystemId: "vpc-1234"}
SubnetIID	Subnet 식별자	● {Name: "subnet-01", SystemId: "subnet-1234"}
SecurityGroupIIds	보안 그룹 목록	● [{Name: "sg-01", SystemId: "sg-1234"}]
KeyPairIId	키페어 정보	● {Name: "keypair-01", SystemId: "key-1234"}
RootDiskType	루트 디스크 타입	● "gp2", "Premium SSD" 등
RootDiskSize	루트 디스크 크기 (GB)	● "30", "100" 등
RootDeviceName	루트 디바이스 이름	● "/dev/sda1"
DataDiskIIDs	데이터 디스크 목록	● [{Name: "disk-01", SystemId: "vol-1234"}]
VMUserId	VM 접속 사용자 ID	● "cb-user" (CB-Spider 추상화된 사용자)
VMUserPasswd	VM 사용자 비밀번호 (Windows만 해당)	● "password1234"
NetworkInterface	네트워크 인터페이스	● "eni-12345678"
PublicIP	공인 IP 주소	● "1.2.3.4"
PublicDNS	공인 DNS 이름	● "ec2-1-2-3-4.compute-1.amazonaws.com"
PrivateIP	사설 IP 주소	● "10.0.0.10"
PrivateDNS	사설 DNS 이름	● "ip-10-0-0-10.ec2.internal"
Platform	플랫폼 타입	● "LINUX/UNIX" 또는 "WINDOWS"
AccessPoint	SSH/RDP 접속 포인트	● "1.2.3.4:22" (Linux), "1.2.3.4:3389" (Windows)
TagList	VM에 할당된 태그 리스트	● [{Key: "Name", Value: "MyVM"}]
KeyValueList	CSP가 제공하는 추가 정보	● [{Key: "Architecture", Value: "x86_64"}]

VM 상태 정보 (VMStatus)

상태	설명
Creating	VM 생성 중
Running	VM 실행 중
Suspending	VM 중지 중
Suspended	VM 중지됨
Resuming	VM 재개 중
Rebooting	VM 재부팅 중
Terminating	VM 종료 중
Terminated	VM 종료됨
NotExist	VM이 존재하지 않음
Failed	VM 오류 상태

주요 필드 설명:

ImageType: PublicImage(퍼블릭 이미지) 또는 MyImage(사용자 스냅샷 이미지)
VMUserId: CB-Spider에서는 항상 "cb-user" 추상화된 사용자 사용
Platform: LINUX/UNIX 또는 WINDOWS
AccessPoint: SSH(Linux) 또는 RDP(Windows) 접속 포인트

3. CB-Spider VM API 및 제공 정보 예시

3.1 VM 생성 예시 (Linux)

AWS에서 Ubuntu VM을 생성하는 API 호출 및 결과 예시:

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

응답 예시:

{
  "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 생성 예시 (Windows)

Windows VM 생성 시 VMUserId와 VMUserPasswd 지정:

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": "ami-000832ed5212e3687",
      "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 Data Disk를 포함한 VM 생성 예시

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": "ami-009e2f5f8d69abd47",
      "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 목록 조회 예시

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

응답 예시:

{
  "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 상태 조회 예시

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

응답 예시:

{
  "Status": "Running"
}

3.6 VM 제어 예시

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

응답 예시:

{
  "Status": "Suspended"
}

3.7 VM 종료 예시

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

응답 예시:

{
  "Status": "Terminated"
}

3.8 강제 종료 (force) 예시

연결된 리소스가 있어도 강제로 VM을 종료:

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 제공 예시

다음 순서로 대상 CSP 선택 및 VM 정보를 관리한다.
1. Connection 선택: AdminWeb 상단에서 대상 CSP Connection 선택
2. VM 메뉴 접근: 좌측 메뉴에서 "VM" 선택
3. VM 생성: "Start VM" 버튼 클릭 후 필요한 정보 입력
4. VM 관리: 생성된 VM의 상태 확인, 제어, 종료 등 수행

4.1 VM 목록 화면 예시

AdminWeb에서 VM 목록을 조회하면 다음과 같은 정보가 표시된다:

VM Name
VM Status (Running, Suspended, etc.)
Public IP / Private IP
VM Spec
Platform (LINUX/UNIX, WINDOWS)
생성 시간
작업 버튼 (상세보기, 제어, 종료 등)

4.2 VM 생성 화면 예시

AdminWeb에서 VM 생성 시 다음 정보를 입력한다:

VM Name: CB-Spider에서 관리할 VM 이름
Image Type: PublicImage 또는 MyImage
Image Name: 사용할 이미지 선택
VM Spec: 인스턴스 타입 선택
VPC/Subnet: 네트워크 구성 선택
Security Groups: 보안 그룹 선택 (복수 선택 가능)
KeyPair: SSH 접속용 키페어 선택
Root Disk: 디스크 타입 및 크기 지정
Data Disks (선택): 추가 데이터 디스크 선택
Tags (선택): 리소스 태그 정보

4.3 VM 상세 화면 예시

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

기본 정보:

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

네트워크 정보:

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

스펙 및 디스크:

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

접속 정보:

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

작업 버튼:

Control VM: Suspend, Resume, Reboot
Terminate VM: VM 종료
Refresh: 정보 갱신

5. VM 생명주기 관리

5.1 VM 생명주기 상태 전이도

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

5.2 VM 상태별 가능한 작업

현재 상태	가능한 작업
Creating	대기 (생성 완료까지)
Running	Suspend, Reboot, Terminate
Suspending	대기 (중지 완료까지)
Suspended	Resume, Terminate
Resuming	대기 (재개 완료까지)
Rebooting	대기 (재부팅 완료까지)
Terminating	대기 (종료 완료까지)
Terminated	삭제됨

6. 주의사항 및 제약사항

6.1 VM 생성 시 주의사항

필수 리소스 사전 생성: VPC, Subnet, Security Group, KeyPair는 VM 생성 전에 미리 생성되어 있어야 함
Zone 일치: Subnet과 DataDisk는 동일한 Zone에 있어야 함
Image Type 선택: PublicImage(퍼블릭 이미지) 또는 MyImage(스냅샷 이미지) 중 선택
Windows VM: VMUserId와 VMUserPasswd 필수 지정
Root Disk 크기: CSP별 최소/최대 크기 제약 확인 필요

6.2 VM 종료 시 주의사항

데이터 백업: VM 종료 시 Root Disk 데이터는 삭제되므로 필요한 데이터는 사전 백업 필요
강제 종료: force=true 옵션 사용 시 연결된 리소스와의 관계 검증 없이 강제 종료됨 (주의!)

6.3 VM 접속

Linux VM: SSH 접속 - ssh -i keypair.pem cb-user@<Public-IP>
Windows VM: RDP 접속 - Windows 원격 데스크톱 연결로 <Public-IP>:3389 접속
VMUserId: CB-Spider는 모든 VM에 "cb-user" 계정 자동 생성 (추상화된 사용자)
KeyPair: Linux VM 접속 시 필수, Private Key 안전 보관 필요

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

VM Management Guide

1. CB-Spider VM 개요

2. CB-Spider VM API 및 제공 정보 규격

2.1 VM 생명주기 관리 API

2.2 제공 정보 규격

3. CB-Spider VM API 및 제공 정보 예시

3.1 VM 생성 예시 (Linux)

3.2 VM 생성 예시 (Windows)

3.3 Data Disk를 포함한 VM 생성 예시

3.4 VM 목록 조회 예시

3.5 VM 상태 조회 예시

3.6 VM 제어 예시

3.7 VM 종료 예시

3.8 강제 종료 (force) 예시

4. CB-Spider VM AdminWeb 제공 예시

4.1 VM 목록 화면 예시

4.2 VM 생성 화면 예시

4.3 VM 상세 화면 예시

5. VM 생명주기 관리

5.1 VM 생명주기 상태 전이도

5.2 VM 상태별 가능한 작업

6. 주의사항 및 제약사항

6.1 VM 생성 시 주의사항

6.2 VM 종료 시 주의사항

6.3 VM 접속

7. 참고 자료

⚠️ GitHub.com Fallback ⚠️

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

VM Management Guide

1. CB-Spider VM 개요

2. CB-Spider VM API 및 제공 정보 규격

2.1 VM 생명주기 관리 API

2.2 제공 정보 규격

3. CB-Spider VM API 및 제공 정보 예시

3.1 VM 생성 예시 (Linux)

3.2 VM 생성 예시 (Windows)

3.3 Data Disk를 포함한 VM 생성 예시

3.4 VM 목록 조회 예시

3.5 VM 상태 조회 예시

3.6 VM 제어 예시

3.7 VM 종료 예시

3.8 강제 종료 (force) 예시

4. CB-Spider VM AdminWeb 제공 예시

4.1 VM 목록 화면 예시

4.2 VM 생성 화면 예시

4.3 VM 상세 화면 예시

5. VM 생명주기 관리

5.1 VM 생명주기 상태 전이도

5.2 VM 상태별 가능한 작업

6. 주의사항 및 제약사항

6.1 VM 생성 시 주의사항

6.2 VM 종료 시 주의사항

6.3 VM 접속

7. 참고 자료

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️