Skip to content

Region Zone Info Guide

Jump to bottom Edit New page
powerkimhub edited this page Mar 20, 2026 · 3 revisions

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:

3. CB-Spider Region/Zone API Specification

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

7. References

Add a custom footer

Table of contents

Clone this wiki locally