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

VPC/Subnet Management Guide

Language: English | 한국어

1. CB-Spider VPC/Subnet Overview

  • Users can create an isolated network environment by setting a VPC (Virtual Private Cloud) Name and configure Subnets within that VPC to deploy resources such as VMs.
  • The relationship between VPC/Subnet information provided by CB-Spider and VM creation utilizing these resources is shown in the diagram below.
  • Users can configure their desired network environment (IP ranges, Zones, etc.) using the abstracted CB-Spider VPC/Subnet information.
┌─────────────────────────────────────────────────────────────┐
│                     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 and Information Specification

  • Users can receive VPC/Subnet information in JSON format using the following CB-Spider REST API.

2.1 VPC Management API

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

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

# VPC List Query (All)
GET    /spider/allvpc                   - List All VPCs (CB-Spider + CSP)
GET    /spider/allvpcinfo               - List All VPCs Info

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

# Direct CSP VPC Deletion
DELETE /spider/cspvpc/{Id}              - Delete CSP VPC

2.2 Subnet Management API

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

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

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

# Direct CSP Subnet Deletion
DELETE /spider/vpc/{VPCName}/cspsubnet/{Id} - Remove CSP Subnet

2.3 Information Specification

VPC Information (VPCInfo)

Field Description Examples
IId VPC identifier information (NameId, SystemId) ● {Name: "vpc-01", SystemId: "vpc-1234abcd"}
IPv4_CIDR VPC IPv4 CIDR block ● "10.0.0.0/16", "172.16.0.0/12", etc.● Some CSPs do not support VPC CIDR
SubnetInfoList List of Subnet information within the VPC ● See Subnet information below
TagList List of tags assigned to the VPC ● [{Key: "Environment", Value: "Production"}]
KeyValueList Additional VPC information provided by CSP in Key/Value List format ● [{Key: "State", Value: "available"}]

Subnet Information (SubnetInfo)

Field Description Examples
IId Subnet identifier information (NameId, SystemId) ● {Name: "subnet-01", SystemId: "subnet-5678efgh"}
Zone Availability Zone where the Subnet is located ● "us-east-1a", "ap-northeast-2a", etc.
IPv4_CIDR Subnet IPv4 CIDR block ● "10.0.0.0/24", "10.0.1.0/24", etc.
TagList List of tags assigned to the Subnet ● [{Key: "Tier", Value: "Public"}]
KeyValueList Additional Subnet information provided by CSP in Key/Value List format ● [{Key: "AvailableIpAddressCount", Value: "251"}]

3. CB-Spider VPC/Subnet API and Information Examples

3.1 VPC Creation Example

  • API call and result example for creating a vpc-01 VPC with 3 Subnets in AWS:
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

Response Example:

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

  • API call and provided information example for AWS vpc-01 VPC:
curl -sX 'GET' 'http://localhost:1024/spider/vpc/vpc-01?ConnectionName=aws-config01' | jq

Response Example:

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

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

Response Example:

{
  "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 Addition Example

  • API call example for adding a new Subnet to an existing VPC:
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

Response Example:

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

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

Response Example:

{
  "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 Deletion Example

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

Response Example:

{
  "Result": "true"
}

3.7 VPC Deletion Example

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

Response Example:

{
  "Result": "true"
}

3.8 Force Delete Example

  • When there are resources (VMs, Security Groups, etc.) connected to a VPC or Subnet, you can forcefully delete them using the force=true option.
# Force delete VPC
curl -sX 'DELETE' 'http://localhost:1024/spider/vpc/vpc-01?force=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

# Force delete 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 Examples

  • Follow these steps to select the target CSP and request VPC/Subnet information:

    1. Select Connection: Choose the target CSP Connection from the top of AdminWeb
    2. Access VPC Menu: Select "VPC" from the left menu
    3. Create VPC: Click "Create VPC" button and enter required information
    4. Manage Subnet: Add/delete Subnets from the VPC details screen

4.1 VPC List Screen Example

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

  • VPC Name
  • VPC SystemId (CSP ID)
  • IPv4 CIDR
  • Number of Subnets
  • State
  • Creation Time
  • Action Buttons (Details, Delete, etc.)

4.2 VPC Creation Screen Example

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

  • VPC Name: VPC name to be managed in CB-Spider
  • IPv4 CIDR: IP range of the VPC (e.g., 10.0.0.0/16)
  • Subnet Information (at least 1 required):
    • Subnet Name
    • Zone (Availability Zone)
    • IPv4 CIDR (within VPC CIDR range)
    • Tags (optional)

4.3 VPC Details Screen Example

The VPC details screen provides the following information and actions:

Basic Information:

  • VPC IId (NameId, SystemId)
  • IPv4 CIDR
  • State
  • KeyValueList (Additional CSP information)

Subnet Management:

  • Display Subnet list
  • Add Subnet button: Add new Subnet
  • Remove button: Delete individual Subnet
  • View Subnet details

Action Buttons:

  • Delete VPC: Delete VPC
  • Refresh: Refresh information

5. Main Usage Scenarios

5.1 Configuring a New Network Environment

  1. Create VPC (Create VPC)
  2. Add required Subnets (Add Subnet)
  3. Create and connect Security Group
  4. Specify the VPC/Subnet when creating VMs

5.2 Integration with Existing CSP VPC

  1. Check the information (SystemId) of VPC that already exists in CSP
  2. Register to CB-Spider through Register VPC API
  3. Manage the VPC in CB-Spider

5.3 Multi-Zone High Availability Configuration

  1. Create a single VPC
  2. Add multiple Subnets in different Zones
    • Zone A: 10.0.0.0/24
    • Zone B: 10.0.1.0/24
    • Zone C: 10.0.2.0/24
  3. Distribute VMs across each Subnet

6. Precautions and Limitations

6.1 VPC CIDR Support Differences by CSP

  • AWS: VPC CIDR required, supports /16 ~ /28 range
  • Azure: Virtual Network CIDR required, supports /8 ~ /29 range
  • GCP: VPC CIDR auto-assigned (only specify CIDR per Subnet)
  • Alibaba: VPC CIDR required, supports /8 ~ /24 range

6.2 Subnet CIDR Configuration

  • Subnet CIDR must be within the VPC CIDR range
  • Subnet CIDRs must not overlap
  • Number of reserved IP addresses varies by CSP (usually 5)

6.3 VPC/Subnet Deletion

  • When deleting a VPC, all Subnets within it are also deleted
  • VPC/Subnet with connected VMs, Security Groups, etc. cannot be deleted
  • Force delete (force=true) deletes connected resources as well (Caution!)

6.4 Zone Specification

  • Zone specification is optional when creating Subnet
  • If Zone is not specified, the Connection's default Zone is used
  • Some CSPs do not allow Zone selection (region-level Subnet)

7. API Response Codes

HTTP Status Description
200 OK Request successful
400 Bad Request Invalid request (JSON structure error, missing required fields, etc.)
404 Not Found Resource not found
500 Internal Server Error Internal server error

8. References