Region Zone Info Guide - cloud-barista/cb-spider GitHub Wiki

Region/Zone Info Guide

Language: English | 한국어

1. CB-Spider Region/Zone Info Overview

CB-Spider provides Region and Zone information for each CSP through a unified API.
Region/Zone APIs are available in two modes:
- Before connection configuration: Query using only DriverName and CredentialName (no ConnectionConfig required)
  - Primarily used to check the list of Regions provided by the target CSP when registering a Region during Connection Management
- After connection configuration: Query using ConnectionName
The original Region/Zone data from the CSP is also available via the OrgRegion and OrgZone APIs.
Supported CSPs: AWS, Azure, GCP, Alibaba, Tencent, OpenStack, NCP, NHN, KT, KTCLASSIC

┌──────────────────────────────────────────────────────────────────┐
│                  CB-Spider Region/Zone Info                      │
│                                                                  │
│  ① Before Connection Configuration                               │
│     DriverName + CredentialName                                  │
│        ├── ListRegionZone()   → All Region+Zone list             │
│        ├── GetRegionZone()    → Specific Region+Zone info        │
│        └── ListOrgRegion()    → Original CSP Region list         │
│                                                                  │
│  ② After Connection Configuration                                │
│     ConnectionName                                               │
│        ├── ListRegionZone()   → All Region+Zone list             │
│        ├── GetRegionZone()    → Specific Region+Zone info        │
│        ├── ListOrgRegion()    → Original CSP Region list         │
│        └── ListOrgZone()      → Original CSP Zone list           │
└──────────────────────────────────────────────────────────────────┘

2. Prerequisites

2.1 Common

The target CSP Driver and Credential must be registered in CB-Spider.
For post-config APIs, the Connection Configuration (ConnectionName) must also be registered.

2.2 AWS, Alibaba, Tencent — Default Region/Zone Setting Required

These CSPs require a target Region to be specified when calling their APIs.
- AWS, Alibaba: The target Region is mandatory for CSP API execution requests.
- Tencent: The driver verifies whether a Zone setting is configured before Connection setup (not required in the Tencent API itself, but enforced for driver stability).
For pre-config Region/Zone queries, a default Region/Zone is set in cloudos_meta.yaml.
The default is currently set to each CSP's Seoul Region and first Zone, and can be changed as needed.
References:
- cloudos_meta.yaml L19

3. CB-Spider Region/Zone API Specification

Region/Zone information is available via the CB-Spider REST API.

3.1 API Endpoints

# ① Before Connection Configuration  (DriverName + CredentialName required)
GET /spider/preconfig/regionzone               - List all RegionZones
GET /spider/preconfig/regionzone/{RegionName}  - Get a specific RegionZone
GET /spider/preconfig/orgregion                - List original CSP Regions

# ② After Connection Configuration  (ConnectionName required)
GET /spider/regionzone                         - List all RegionZones
GET /spider/regionzone/{RegionName}            - Get a specific RegionZone
GET /spider/orgregion                          - List original CSP Regions
GET /spider/orgzone                            - List original CSP Zones

3.2 Request Parameters

① Before Connection Configuration

Parameter	Description	Example
`DriverName`	Registered cloud driver name	`aws-driver01`
`CredentialName`	Registered credential name	`aws-credential01`

② After Connection Configuration

Parameter	Description	Example
`ConnectionName`	Registered connection configuration name	`aws-config01`

3.3 Response Schema

RegionZone (per region entry)

Field	Description	Example
`Name`	Region identifier used in CB-Spider	`ap-northeast-2`
`DisplayName`	Region display name used in CB-Spider	`South Korea, Seoul`
`CSPDisplayName`	Region display name provided by the CSP	`Asia Pacific (Seoul)`
`ZoneList`	List of zones within the region	See ZoneInfo below

ZoneInfo (per zone entry in ZoneList)

Field	Description	Example
`Name`	Zone identifier	`ap-northeast-2a`
`DisplayName`	Zone display name used in CB-Spider	`South Korea, Seoul`
`CSPDisplayName`	Zone display name provided by the CSP	`Asia Pacific (Seoul)`
`Status`	Zone availability status	`Available`

Note

OrgRegion and OrgZone responses are passed through from the CSP as-is, and their structure varies per CSP.

The OrgZone API (GET /spider/orgzone) is only available in post-config mode.

4. CB-Spider Region/Zone API Examples

4.1 Before Connection Configuration

(1) List all RegionZones

curl -sX GET "http://localhost:1024/spider/preconfig/regionzone?DriverName=aws-driver01&CredentialName=aws-credential01" | json_pp

Response example:

{
   "regionzone" : [
      {
         "CSPDisplayName" : "Asia Pacific (Seoul)",
         "DisplayName" : "South Korea, Seoul",
         "Name" : "ap-northeast-2",
         "ZoneList" : [
            {
               "CSPDisplayName" : "Asia Pacific (Seoul)",
               "DisplayName" : "South Korea, Seoul",
               "Name" : "ap-northeast-2a",
               "Status" : "Available"
            },
            {
               "CSPDisplayName" : "Asia Pacific (Seoul)",
               "DisplayName" : "South Korea, Seoul",
               "Name" : "ap-northeast-2b",
               "Status" : "Available"
            }
         ]
      }
   ]
}

(2) Get a specific RegionZone

curl -sX GET "http://localhost:1024/spider/preconfig/regionzone/ap-northeast-2?DriverName=aws-driver01&CredentialName=aws-credential01" | json_pp

Response example:

{
   "CSPDisplayName" : "Asia Pacific (Seoul)",
   "DisplayName" : "South Korea, Seoul",
   "Name" : "ap-northeast-2",
   "ZoneList" : [
      {
         "CSPDisplayName" : "Asia Pacific (Seoul)",
         "DisplayName" : "South Korea, Seoul",
         "Name" : "ap-northeast-2a",
         "Status" : "Available"
      }
   ]
}

(3) List original CSP Regions

curl -sX GET "http://localhost:1024/spider/preconfig/orgregion?DriverName=aws-driver01&CredentialName=aws-credential01" | json_pp

Response example:

{
   "RegionInfo" : {
      "Regions" : [
         {
            "Endpoint" : "ec2.ap-south-1.amazonaws.com",
            "OptInStatus" : "opt-in-not-required",
            "RegionName" : "ap-south-1"
         },
         {
            "Endpoint" : "ec2.eu-south-1.amazonaws.com",
            "OptInStatus" : "opted-in",
            "RegionName" : "eu-south-1"
         }
      ]
   }
}

4.2 After Connection Configuration

(1) List all RegionZones

curl -sX GET "http://localhost:1024/spider/regionzone?ConnectionName=aws-config01" | json_pp

(2) Get a specific RegionZone

curl -sX GET "http://localhost:1024/spider/regionzone/ap-northeast-2?ConnectionName=aws-config01" | json_pp

(3) List original CSP Regions

curl -sX GET "http://localhost:1024/spider/orgregion?ConnectionName=aws-config01" | json_pp

(4) List original CSP Zones

curl -sX GET "http://localhost:1024/spider/orgzone?ConnectionName=aws-config01" | json_pp

Response example:

{
   "ZoneInfo" : [
      {
         "AvailabilityZones" : [
            {
               "GroupName" : "ap-south-1",
               "Messages" : null,
               "NetworkBorderGroup" : "ap-south-1",
               "OptInStatus" : "opt-in-not-required",
               "ParentZoneId" : null,
               "ParentZoneName" : null,
               "RegionName" : "ap-south-1",
               "State" : "available",
               "ZoneId" : "aps1-az1",
               "ZoneName" : "ap-south-1a",
               "ZoneType" : "availability-zone"
            }
         ]
      }
   ]
}

5. Caveats

5.1 Default Region/Zone Requirement (AWS, Alibaba, Tencent)

For pre-config Region/Zone queries, AWS and Alibaba require a target Region, and Tencent also requires a Zone setting.
CB-Spider handles this by reading a default Region/Zone from cloudos_meta.yaml before invoking the CSP API.
The defaults can be changed to any desired Region/Zone in cloudos_meta.yaml.

5.2 OrgZone API Availability

The OrgZone API (GET /spider/orgzone) is only available in post-config mode (requires ConnectionName).
There is no pre-config equivalent for OrgZone.

5.3 OrgRegion / OrgZone Response Format Differs per CSP

The OrgRegion and OrgZone responses are passed through from each CSP as-is.
The response structure and field names vary per CSP and are not normalized by CB-Spider.

6. API Response Codes

HTTP Status Code	Description
`200 OK`	Successful response
`400 Bad Request`	Request parameter error (missing required parameter or invalid value)
`500 Internal Server Error`	Server error or CSP API call failure

Region Zone Info Guide - cloud-barista/cb-spider GitHub Wiki

Region/Zone Info Guide

1. CB-Spider Region/Zone Info Overview

2. Prerequisites

2.1 Common

2.2 AWS, Alibaba, Tencent — Default Region/Zone Setting Required

3. CB-Spider Region/Zone API Specification

3.1 API Endpoints

3.2 Request Parameters

3.3 Response Schema

4. CB-Spider Region/Zone API Examples

4.1 Before Connection Configuration

(1) List all RegionZones

(2) Get a specific RegionZone

(3) List original CSP Regions

4.2 After Connection Configuration

(1) List all RegionZones

(2) Get a specific RegionZone

(3) List original CSP Regions

(4) List original CSP Zones

5. Caveats

5.1 Default Region/Zone Requirement (AWS, Alibaba, Tencent)

5.2 OrgZone API Availability

5.3 OrgRegion / OrgZone Response Format Differs per CSP

6. API Response Codes

7. References