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

VPC/Subnet Management Guide

Language: English | 한국어

1. CB-Spider VPC/Subnet 개요

사용자는 VPC(Virtual Private Cloud) Name을 설정하여 격리된 네트워크 환경을 생성하고, 해당 VPC 내에 Subnet을 구성하여 VM 등의 자원을 배치할 수 있다.
CB-Spider가 제공하는 VPC/Subnet 정보 및 이를 활용한 VM 생성과의 관계가 아래 그림과 같다.
사용자는 추상화된 CB-Spider VPC/Subnet 정보를 활용하여 원하는 네트워크 환경(IP 대역, Zone 등)을 구성할 수 있다.

┌─────────────────────────────────────────────────────────────┐
│                     CB-Spider VPC/Subnet                    │
│                                                             │
│  VPC (10.0.0.0/16)                                          │
│  ├── Subnet-1 (10.0.0.0/24, us-east-1a)                     │
│  │   └── VM-1, VM-2, ...                                    │
│  ├── Subnet-2 (10.0.1.0/24, us-east-1b)                     │
│  │   └── VM-3, VM-4, ...                                    │
│  └── Subnet-3 (10.0.2.0/24, us-east-1c)                     │
│      └── VM-5, VM-6, ...                                    │
└─────────────────────────────────────────────────────────────┘

2. CB-Spider VPC/Subnet API 및 제공 정보 규격

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

2.1 VPC 관리 API

# VPC 관리
POST   /spider/vpc                      - Create VPC
GET    /spider/vpc                      - List VPCs
GET    /spider/vpc/{Name}               - Get VPC
DELETE /spider/vpc/{Name}               - Delete VPC

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

# VPC 목록 조회 (전체)
GET    /spider/allvpc                   - List All VPCs (CB-Spider + CSP)
GET    /spider/allvpcinfo               - List All VPCs Info

# VPC 통계
GET    /spider/countvpc                 - Count All VPCs
GET    /spider/countvpc/{ConnectionName} - Count VPCs by Connection

# CSP VPC 직접 삭제
DELETE /spider/cspvpc/{Id}              - Delete CSP VPC

2.2 Subnet 관리 API

# Subnet 관리
POST   /spider/vpc/{VPCName}/subnet     - Add Subnet
GET    /spider/vpc/{VPCName}/subnet/{SubnetName} - Get Subnet
DELETE /spider/vpc/{VPCName}/subnet/{SubnetName} - Remove Subnet

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

# Subnet 통계
GET    /spider/countsubnet              - Count All Subnets
GET    /spider/countsubnet/{ConnectionName} - Count Subnets by Connection

# CSP Subnet 직접 삭제
DELETE /spider/vpc/{VPCName}/cspsubnet/{Id} - Remove CSP Subnet

2.3 제공 정보 규격

VPC 정보 (VPCInfo)

필드	설명	예시
IId	VPC의 식별자 정보 (NameId, SystemId)	● {Name: "vpc-01", SystemId: "vpc-1234abcd"}
IPv4_CIDR	VPC의 IPv4 CIDR 블록	● "10.0.0.0/16", "172.16.0.0/12" 등● 일부 CSP는 VPC CIDR 미지원
SubnetInfoList	VPC 내 Subnet 정보 리스트	● 아래 Subnet 정보 참조
TagList	VPC에 할당된 태그 리스트	● [{Key: "Environment", Value: "Production"}]
KeyValueList	CSP가 제공하는 추가 VPC 정보를 Key/Value List 형태로 제공	● [{Key: "State", Value: "available"}]

Subnet 정보 (SubnetInfo)

필드	설명	예시
IId	Subnet의 식별자 정보 (NameId, SystemId)	● {Name: "subnet-01", SystemId: "subnet-5678efgh"}
Zone	Subnet이 위치한 가용영역(Zone)	● "us-east-1a", "ap-northeast-2a" 등
IPv4_CIDR	Subnet의 IPv4 CIDR 블록	● "10.0.0.0/24", "10.0.1.0/24" 등
TagList	Subnet에 할당된 태그 리스트	● [{Key: "Tier", Value: "Public"}]
KeyValueList	CSP가 제공하는 추가 Subnet 정보를 Key/Value List 형태로 제공	● [{Key: "AvailableIpAddressCount", Value: "251"}]

3. CB-Spider VPC/Subnet API 및 제공 정보 예시

3.1 VPC 생성 예시

AWS에서 vpc-01 VPC와 3개의 Subnet을 생성하는 API 호출 및 결과 예시가 다음과 같다.

curl -sX 'POST' 'http://localhost:1024/spider/vpc' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "vpc-01",
      "IPv4_CIDR": "10.0.0.0/16",
      "SubnetInfoList": [
        {
          "Name": "subnet-01",
          "Zone": "us-east-1a",
          "IPv4_CIDR": "10.0.0.0/24"
        },
        {
          "Name": "subnet-02",
          "Zone": "us-east-1b",
          "IPv4_CIDR": "10.0.1.0/24"
        },
        {
          "Name": "subnet-03",
          "Zone": "us-east-1c",
          "IPv4_CIDR": "10.0.2.0/24"
        }
      ]
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "vpc-01",
    "SystemId": "vpc-0a1b2c3d4e5f67890"
  },
  "IPv4_CIDR": "10.0.0.0/16",
  "SubnetInfoList": [
    {
      "IId": {
        "NameId": "subnet-01",
        "SystemId": "subnet-0a1b2c3d"
      },
      "Zone": "us-east-1a",
      "IPv4_CIDR": "10.0.0.0/24",
      "KeyValueList": [
        {
          "Key": "AvailableIpAddressCount",
          "Value": "251"
        },
        {
          "Key": "State",
          "Value": "available"
        }
      ]
    },
    {
      "IId": {
        "NameId": "subnet-02",
        "SystemId": "subnet-1b2c3d4e"
      },
      "Zone": "us-east-1b",
      "IPv4_CIDR": "10.0.1.0/24",
      "KeyValueList": [
        {
          "Key": "AvailableIpAddressCount",
          "Value": "251"
        },
        {
          "Key": "State",
          "Value": "available"
        }
      ]
    },
    {
      "IId": {
        "NameId": "subnet-03",
        "SystemId": "subnet-2c3d4e5f"
      },
      "Zone": "us-east-1c",
      "IPv4_CIDR": "10.0.2.0/24",
      "KeyValueList": [
        {
          "Key": "AvailableIpAddressCount",
          "Value": "251"
        },
        {
          "Key": "State",
          "Value": "available"
        }
      ]
    }
  ],
  "KeyValueList": [
    {
      "Key": "State",
      "Value": "available"
    },
    {
      "Key": "IsDefault",
      "Value": "false"
    },
    {
      "Key": "DhcpOptionsId",
      "Value": "dopt-0a1b2c3d"
    }
  ]
}

3.2 VPC 조회 예시

AWS vpc-01 VPC 정보 호출 API 및 제공 정보 예시가 다음과 같다.

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

응답 예시:

{
  "IId": {
    "NameId": "vpc-01",
    "SystemId": "vpc-0a1b2c3d4e5f67890"
  },
  "IPv4_CIDR": "10.0.0.0/16",
  "SubnetInfoList": [
    {
      "IId": {
        "NameId": "subnet-01",
        "SystemId": "subnet-0a1b2c3d"
      },
      "Zone": "us-east-1a",
      "IPv4_CIDR": "10.0.0.0/24"
    },
    {
      "IId": {
        "NameId": "subnet-02",
        "SystemId": "subnet-1b2c3d4e"
      },
      "Zone": "us-east-1b",
      "IPv4_CIDR": "10.0.1.0/24"
    },
    {
      "IId": {
        "NameId": "subnet-03",
        "SystemId": "subnet-2c3d4e5f"
      },
      "Zone": "us-east-1c",
      "IPv4_CIDR": "10.0.2.0/24"
    }
  ],
  "KeyValueList": [
    {
      "Key": "State",
      "Value": "available"
    }
  ]
}

3.3 VPC 목록 조회 예시

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

응답 예시:

{
  "vpc": [
    {
      "IId": {
        "NameId": "vpc-01",
        "SystemId": "vpc-0a1b2c3d4e5f67890"
      },
      "IPv4_CIDR": "10.0.0.0/16",
      "SubnetInfoList": [...]
    },
    {
      "IId": {
        "NameId": "vpc-02",
        "SystemId": "vpc-1b2c3d4e5f678901"
      },
      "IPv4_CIDR": "172.16.0.0/16",
      "SubnetInfoList": [...]
    }
  ]
}

3.4 Subnet 추가 예시

기존 VPC에 새로운 Subnet을 추가하는 API 호출 예시가 다음과 같다.

curl -sX 'POST' 'http://localhost:1024/spider/vpc/vpc-01/subnet' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "subnet-04",
      "Zone": "us-east-1d",
      "IPv4_CIDR": "10.0.3.0/24",
      "TagList": [
        {
          "Key": "Tier",
          "Value": "Private"
        }
      ]
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "vpc-01",
    "SystemId": "vpc-0a1b2c3d4e5f67890"
  },
  "IPv4_CIDR": "10.0.0.0/16",
  "SubnetInfoList": [
    {
      "IId": {
        "NameId": "subnet-01",
        "SystemId": "subnet-0a1b2c3d"
      },
      "Zone": "us-east-1a",
      "IPv4_CIDR": "10.0.0.0/24"
    },
    {
      "IId": {
        "NameId": "subnet-02",
        "SystemId": "subnet-1b2c3d4e"
      },
      "Zone": "us-east-1b",
      "IPv4_CIDR": "10.0.1.0/24"
    },
    {
      "IId": {
        "NameId": "subnet-03",
        "SystemId": "subnet-2c3d4e5f"
      },
      "Zone": "us-east-1c",
      "IPv4_CIDR": "10.0.2.0/24"
    },
    {
      "IId": {
        "NameId": "subnet-04",
        "SystemId": "subnet-3d4e5f6a"
      },
      "Zone": "us-east-1d",
      "IPv4_CIDR": "10.0.3.0/24",
      "TagList": [
        {
          "Key": "Tier",
          "Value": "Private"
        }
      ]
    }
  ]
}

3.5 Subnet 조회 예시

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

응답 예시:

{
  "IId": {
    "NameId": "subnet-01",
    "SystemId": "subnet-0a1b2c3d"
  },
  "Zone": "us-east-1a",
  "IPv4_CIDR": "10.0.0.0/24",
  "KeyValueList": [
    {
      "Key": "AvailableIpAddressCount",
      "Value": "251"
    },
    {
      "Key": "State",
      "Value": "available"
    }
  ]
}

3.6 Subnet 삭제 예시

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

응답 예시:

{
  "Result": "true"
}

3.7 VPC 삭제 예시

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

응답 예시:

{
  "Result": "true"
}

3.8 강제 삭제 (force) 예시

VPC 또는 Subnet에 연결된 자원(VM, Security Group 등)이 있을 경우, force=true 옵션을 사용하여 강제 삭제할 수 있다.

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

# Subnet 강제 삭제
curl -sX 'DELETE' 'http://localhost:1024/spider/vpc/vpc-01/subnet/subnet-01?force=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

4. CB-Spider VPC/Subnet AdminWeb 제공 예시

다음 순서로 대상 CSP 선택 및 VPC/Subnet 정보를 요청한다.
1. Connection 선택: AdminWeb 상단에서 대상 CSP Connection 선택
2. VPC 메뉴 접근: 좌측 메뉴에서 "VPC" 선택
3. VPC 생성: "Create VPC" 버튼 클릭 후 필요한 정보 입력
4. Subnet 관리: VPC 상세 화면에서 Subnet 추가/삭제 가능

4.1 VPC 목록 화면 예시

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

VPC Name
VPC SystemId (CSP ID)
IPv4 CIDR
Subnet 개수
상태 (State)
생성 시간
작업 버튼 (상세보기, 삭제 등)

4.2 VPC 생성 화면 예시

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

VPC Name: CB-Spider에서 관리할 VPC 이름
IPv4 CIDR: VPC의 IP 대역 (예: 10.0.0.0/16)
Subnet 정보 (1개 이상 필수):
- Subnet Name
- Zone (가용영역)
- IPv4 CIDR (VPC CIDR 범위 내)
- Tags (선택)

4.3 VPC 상세 화면 예시

VPC 상세 화면에서는 다음 정보와 작업이 가능하다:

기본 정보:

VPC IId (NameId, SystemId)
IPv4 CIDR
State
KeyValueList (CSP 추가 정보)

Subnet 관리:

Subnet 목록 표시
Add Subnet 버튼: 새 Subnet 추가
Remove 버튼: 개별 Subnet 삭제
Subnet 상세 정보 보기

작업 버튼:

Delete VPC: VPC 삭제
Refresh: 정보 갱신

5. 주요 사용 시나리오

5.1 새로운 네트워크 환경 구성

VPC 생성 (Create VPC)
필요한 Subnet 추가 (Add Subnet)
Security Group 생성 및 연결
VM 생성 시 해당 VPC/Subnet 지정

5.2 기존 CSP VPC 연동

CSP에 이미 존재하는 VPC의 정보 확인 (SystemId)
Register VPC API를 통해 CB-Spider에 등록
CB-Spider에서 해당 VPC 관리 가능

5.3 Multi-Zone 고가용성 구성

하나의 VPC 생성
서로 다른 Zone에 여러 Subnet 추가
- Zone A: 10.0.0.0/24
- Zone B: 10.0.1.0/24
- Zone C: 10.0.2.0/24
각 Subnet에 VM 분산 배치

6. 주의사항 및 제약사항

6.1 CSP별 VPC CIDR 지원 차이

AWS: VPC CIDR 필수, /16 ~ /28 범위 지원
Azure: Virtual Network CIDR 필수, /8 ~ /29 범위 지원
GCP: VPC CIDR 자동 할당 (Subnet별 CIDR만 지정)
Alibaba: VPC CIDR 필수, /8 ~ /24 범위 지원

6.2 Subnet CIDR 설정

Subnet CIDR은 VPC CIDR 범위 내에 있어야 함
Subnet 간 CIDR이 겹치지 않아야 함
CSP별로 예약된 IP 주소 개수가 다름 (보통 5개)

6.3 VPC/Subnet 삭제

VPC 삭제 시 내부의 모든 Subnet이 함께 삭제됨
VM, Security Group 등이 연결된 VPC/Subnet은 삭제 불가
강제 삭제(force=true) 시 연결된 자원도 함께 삭제됨 (주의!)

6.4 Zone 지정

Subnet 생성 시 Zone 지정은 선택사항
Zone을 지정하지 않으면 Connection의 기본 Zone 사용
일부 CSP는 Zone 선택 불가능 (리전 단위 Subnet)

7. API 응답 코드

HTTP Status	설명
200 OK	요청 성공
400 Bad Request	잘못된 요청 (JSON 구조 오류, 필수 필드 누락 등)
404 Not Found	리소스를 찾을 수 없음
500 Internal Server Error	서버 내부 오류

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

VPC/Subnet Management Guide

1. CB-Spider VPC/Subnet 개요

2. CB-Spider VPC/Subnet API 및 제공 정보 규격

2.1 VPC 관리 API

2.2 Subnet 관리 API

2.3 제공 정보 규격

3. CB-Spider VPC/Subnet API 및 제공 정보 예시

3.1 VPC 생성 예시

3.2 VPC 조회 예시

3.3 VPC 목록 조회 예시

3.4 Subnet 추가 예시

3.5 Subnet 조회 예시

3.6 Subnet 삭제 예시

3.7 VPC 삭제 예시

3.8 강제 삭제 (force) 예시

4. CB-Spider VPC/Subnet AdminWeb 제공 예시

4.1 VPC 목록 화면 예시

4.2 VPC 생성 화면 예시

4.3 VPC 상세 화면 예시

5. 주요 사용 시나리오

5.1 새로운 네트워크 환경 구성

5.2 기존 CSP VPC 연동

5.3 Multi-Zone 고가용성 구성

6. 주의사항 및 제약사항

6.1 CSP별 VPC CIDR 지원 차이

6.2 Subnet CIDR 설정

6.3 VPC/Subnet 삭제

6.4 Zone 지정

7. API 응답 코드

8. 참고 자료