Region/Zone Info Guide

Language: English | 한국어

1. CB-Spider Region/Zone Info 개요

• CB-Spider는 CSP별 Region 및 Zone 정보를 단일 API로 제공한다.
• Region/Zone API는 두 가지 모드로 사용할 수 있다:
  • 연결 설정 전 (Before Connection Configuration): DriverName과 CredentialName만으로 조회 (ConnectionConfig 불필요)
    • 주로 Connection Management시 Region 등록을 위해서 대상 CSP가 제공하는 Region 목록 확인할 때 활용
  • 연결 설정 후 (After Connection Configuration): ConnectionName으로 조회
• CSP 원본 Region/Zone 데이터는 OrgRegion 및 OrgZone API를 통해 별도로 조회할 수 있다.
• 지원 CSP: AWS, Azure, GCP, Alibaba, Tencent, OpenStack, NCP, NHN, KT, KTCLASSIC

┌──────────────────────────────────────────────────────────────────┐
│                  CB-Spider Region/Zone Info                      │
│                                                                  │
│  ① 연결 설정 전 (Before Connection Configuration)                 │
│     DriverName + CredentialName                                  │
│        ├── ListRegionZone()   → 전체 Region+Zone 목록             │
│        ├── GetRegionZone()    → 특정 Region+Zone 상세             │
│        └── ListOrgRegion()    → CSP 원본 Region 목록              │
│                                                                  │
│  ② 연결 설정 후 (After Connection Configuration)                  │
│     ConnectionName                                               │
│        ├── ListRegionZone()   → 전체 Region+Zone 목록            │
│        ├── GetRegionZone()    → 특정 Region+Zone 상세            │
│        ├── ListOrgRegion()    → CSP 원본 Region 목록             │
│        └── ListOrgZone()      → CSP 원본 Zone 목록               │
└──────────────────────────────────────────────────────────────────┘

2. 사전 준비 사항

2.1 공통

• CB-Spider에 대상 CSP의 Driver 및 Credential이 등록되어 있어야 한다.
• 연결 설정 후 API를 사용하려면 Connection Configuration(ConnectionName)도 등록되어 있어야 한다.

2.2 AWS, Alibaba, Tencent — 기본 Region/Zone 설정 필요

• 이들 CSP는 API 호출 시 대상 Region 지정이 필수이다.
  • AWS, Alibaba: CSP API 실행 요청 시 대상 Region 지정이 필수
  • Tencent: 연결 설정 전 Driver 초기화 시 Zone 설정 여부를 검증 (Tencent API 자체에서는 불필요하나 드라이버 안정성을 위해 적용)
• 연결 설정 전 Region/Zone 조회 시, cloudos_meta.yaml에 설정된 기본 Region/Zone을 사용한다.
• 기본값은 각 CSP의 서울 Region 및 첫 번째 Zone으로 설정되어 있으며, 필요에 따라 변경할 수 있다.
• 참고:
  • cloudos_meta.yaml L19

3. CB-Spider Region/Zone API 및 제공 정보 규격

• Region/Zone 정보는 CB-Spider REST API를 통해 JSON 형식으로 조회할 수 있다.

3.1 API 엔드포인트

# ① 연결 설정 전  (DriverName + CredentialName 필요)
GET /spider/preconfig/regionzone               - 전체 RegionZone 목록 조회
GET /spider/preconfig/regionzone/{RegionName}  - 특정 RegionZone 조회
GET /spider/preconfig/orgregion                - CSP 원본 Region 목록 조회

# ② 연결 설정 후  (ConnectionName 필요)
GET /spider/regionzone                         - 전체 RegionZone 목록 조회
GET /spider/regionzone/{RegionName}            - 특정 RegionZone 조회
GET /spider/orgregion                          - CSP 원본 Region 목록 조회
GET /spider/orgzone                            - CSP 원본 Zone 목록 조회

3.2 요청 파라미터

① 연결 설정 전

파라미터	설명	예시
DriverName	등록된 클라우드 드라이버 이름	aws-driver01
CredentialName	등록된 자격증명 이름	aws-credential01

② 연결 설정 후

파라미터	설명	예시
ConnectionName	등록된 연결 설정 이름	aws-config01

3.3 응답 스키마

RegionZone (Region 항목)

필드	설명	예시
Name	CB-Spider에서 사용하는 Region 식별자	ap-northeast-2
DisplayName	CB-Spider에서 사용하는 Region 표시 이름	South Korea, Seoul
CSPDisplayName	CSP가 제공하는 Region 표시 이름	Asia Pacific (Seoul)
ZoneList	해당 Region에 속한 Zone 목록	아래 ZoneInfo 참고

ZoneInfo (ZoneList 내 Zone 항목)

필드	설명	예시
Name	Zone 식별자	ap-northeast-2a
DisplayName	CB-Spider에서 사용하는 Zone 표시 이름	South Korea, Seoul
CSPDisplayName	CSP가 제공하는 Zone 표시 이름	Asia Pacific (Seoul)
Status	Zone 가용 상태	Available

참고

• OrgRegion 및 OrgZone 응답은 CSP 원본 데이터를 그대로 전달하며, CSP별로 구조가 다르다.
• OrgZone API(GET /spider/orgzone)는 연결 설정 후 모드에서만 사용 가능하다.

---

4. CB-Spider Region/Zone API 사용 예시

4.1 연결 설정 전 (Before Connection Configuration)

(1) 전체 RegionZone 목록 조회

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

응답 예시:

{
   "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) 특정 RegionZone 조회

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

응답 예시:

{
   "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) CSP 원본 Region 목록 조회

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

응답 예시:

{
   "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) 전체 RegionZone 목록 조회

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

(2) 특정 RegionZone 조회

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

(3) CSP 원본 Region 목록 조회

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

(4) CSP 원본 Zone 목록 조회

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

응답 예시:

{
   "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. 주의 사항

5.1 기본 Region/Zone 설정 필요 (AWS, Alibaba, Tencent)

• 연결 설정 전 Region/Zone 조회 시, AWS와 Alibaba는 대상 Region 지정이 필수이고, Tencent는 Zone 설정도 필요하다.
• CB-Spider는 cloudos_meta.yaml에서 기본 Region/Zone을 읽어 CSP API를 호출한다.
• 기본값은 cloudos_meta.yaml에서 원하는 Region/Zone으로 변경할 수 있다.

5.2 OrgZone API 사용 가능 범위

• OrgZone API(GET /spider/orgzone)는 연결 설정 후 모드에서만 사용 가능하다 (ConnectionName 필요).
• 연결 설정 전 모드에서는 OrgZone에 해당하는 API가 제공되지 않는다.

5.3 OrgRegion / OrgZone 응답 형식은 CSP별로 상이

• OrgRegion 및 OrgZone 응답은 각 CSP의 원본 데이터를 그대로 전달한다.
• 응답 구조와 필드명은 CSP별로 다르며, CB-Spider에서 정규화하지 않는다.

---

6. API 응답 코드

HTTP 상태 코드	설명
200 OK	정상 응답
400 Bad Request	요청 파라미터 오류 (필수 파라미터 누락 또는 잘못된 값)
500 Internal Server Error	서버 오류 또는 CSP API 호출 실패

---

7. 참고 자료

• CB-Spider REST API (Swagger)
• AdminWeb Region/Zone Info Guide
• Region Zone Driver API Guide