Tag Management Guide(KR)

Tag Management Guide

Language: English | 한국어

1. CB-Spider Tag 관리 개요

• CB-Spider는 연동된 클라우드의 관리 자원들에 Tag 기능을 제공한다.
• 사용자는 Tag를 사용하여 자원들을 그룹화하고 식별할 수 있으며, 이를 통해 대규모 자원의 관리 자동화, 비용 관리 등 다양한 목적에 활용할 수 있다.
• 하나의 Tag는 문자열 Key와 문자열 Value 쌍으로 구성되며, Key 값은 필수이나 Value는 옵션으로 생략 가능하다.
• 사용자는 다음과 같이 두 가지 방법으로 자원에 Tag를 추가할 수 있다.
  1. 자원 생성 시 Tag 설정: 자원 생성 요청 시 TagList를 설정하여 여러 개의 Tag 추가 가능
  2. 기존 자원에 Tag 관리 API 사용: Tag 관리 REST API를 통한 Tag 추가/조회/삭제 가능
• Tag 관리 API는 AddTag, ListTag, GetTag, RemoveTag 4개의 API를 제공한다.
• 지원 대상 자원 타입: VPC, SUBNET, SG, KEY(keypair), VM, NLB, DISK, MYIMAGE, CLUSTER

┌──────────────────────────────────────────────────────────────────┐
│                     CB-Spider Tag Management                     │
│                                                                  │
│  ConnectionName (CSP + Region)                                   │
│        │                                                         │
│        ├── AddTag(ResourceType, ResourceName, Tag)               │
│        │      └── Tag(Key, Value) 추가                           │
│        │                                                         │
│        ├── ListTag(ResourceType, ResourceName)                   │
│        │      └── 해당 자원의 전체 Tag 목록 조회                   │
│        │                                                         │
│        ├── GetTag(ResourceType, ResourceName, Key)               │
│        │      └── 특정 Tag 정보 조회 (Key 기반)                   │
│        │                                                         │
│        └── RemoveTag(ResourceType, ResourceName, Key)            │
│               └── 특정 Tag 삭제 (Key 기반)                        │
│                                                                  │
│  지원 자원 타입                                                   │
│    VPC, SUBNET, SG, KEY(keypair), VM, NLB,                       │
│    DISK, MYIMAGE, CLUSTER                                        │
└──────────────────────────────────────────────────────────────────┘

2. CSP별 Tag 제공 현황

• CSP별 자원별 Tag 제공 현황은 다음과 같다.

  Provider	VPC	Subnet	SecurityGroup	VM KeyPair	VM	Disk	MyImage	NLB	Cluster
  AWS	O	O	O	O	O	O	O	O	O
  Azure	O	-	O	O	O	O	O	O	O
  GCP	-	-	-	-	O	O	-	-	O
  Alibaba	△	△	O	O	O	O	O	O	-
  Tencent	O	O	O	O	O	O	O	O	O
  IBM	O	O	O	O	O	O	O	O	O
  OpenStack	O	O	O	-	O	-	-	O	-
  KT Classic	-	-	-	-	O	O	O	-	-

  ※ △: 자원 생성 시에만 Tagging 제공
  ※  - : CSP가 Tagging을 제공하지 않는 자원
  ※ NHN, NCP, KT VPC: Tagging을 제공하지 않음
     - Tag API 호출시 다음 오류 메시지 반환: "nhn-config does not support TagHandler"
  

  ※ Tag 미지원 자원에 대한 API 호출시 대응
    (1) 자원 생성 요청 시 Tag 설정 요청: 자원은 생성되고, Tag는 추가되지 않음(Log 출력 없음)
    (2) 기존 자원에 Tag 추가 요청: 다음 공통 형식의 에러 메시지 반환(Error Log 출력)
       • format: "[TAG_NOT_SUPPORTED] Tagging is not supported for the resource: {CSP}-{RESOURCE}"
       • example: "[TAG_NOT_SUPPORTED] Tagging is not supported for the resource: GCP-keypair"
  

3. 사전 준비 사항

• 대상 CSP Connection이 정상적으로 등록되어 있어야 한다.
• Tag를 추가/조회할 대상 자원(VPC, VM 등)이 이미 생성되어 있어야 한다.

4. CB-Spider Tag API 및 제공 정보 규격

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

4.1 Tag API

# Tag 추가
POST /spider/tag                  - Add Tag

# Tag 목록 조회
GET  /spider/tag                  - List Tags

# 특정 Tag 조회
GET  /spider/tag/{Key}            - Get Tag

# Tag 삭제
DELETE /spider/tag/{Key}          - Remove Tag

4.2 요청 파라미터

AddTag (POST /spider/tag)

파라미터	설명	예시
ConnectionName	대상 Connection 이름	aws-seoul-config
ReqInfo.ResourceType	자원 타입	VPC, VM, SG 등
ReqInfo.ResourceName	자원 이름	vpc-01, my-vm
ReqInfo.Tag	추가할 Tag (Key, Value 쌍)	{"Key": "env", "Value": "prod"}

ListTag (GET /spider/tag)

파라미터	설명	예시
ConnectionName	대상 Connection 이름	aws-seoul-config
ResourceType	자원 타입	VPC, VM 등
ResourceName	자원 이름	vpc-01

GetTag (GET /spider/tag/{Key})

파라미터	설명	예시
ConnectionName	대상 Connection 이름	aws-seoul-config
ResourceType	자원 타입	VPC, VM 등
ResourceName	자원 이름	vpc-01
Key	조회할 Tag의 Key	env

RemoveTag (DELETE /spider/tag/{Key})

파라미터	설명	예시
ConnectionName	대상 Connection 이름	aws-seoul-config
ReqInfo.ResourceType	자원 타입	VPC, VM 등
ReqInfo.ResourceName	자원 이름	vpc-01
Key	삭제할 Tag의 Key	env

4.3 자원 타입 (ResourceType)

자원 타입	값	설명
VPC	VPC	Virtual Private Cloud
Subnet	SUBNET	Subnet
Security Group	SG	Security Group
KeyPair	KEY	VM SSH KeyPair
VM	VM	Virtual Machine
NLB	NLB	Network Load Balancer
Disk	DISK	Disk (Volume)
MyImage	MYIMAGE	VM Snapshot Image
Cluster	CLUSTER	Kubernetes Cluster

4.4 제공 정보 규격

Tag 정보 (KeyValue)

필드	설명	예시
Key	Tag 키 값	env, team, project
Value	Tag 값	production, backend, spider

ListTag 응답 형식

필드	설명
tag	Tag 목록 (KeyValue 배열)
resourceType	자원 타입의 사람이 읽을 수 있는 이름

5. CB-Spider Tag API 예시

5.1 Tag 추가 (AddTag)

curl -u "$SPIDER_USERNAME:$SPIDER_PASSWORD" -sX POST 'http://localhost:1024/spider/tag' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-seoul-config",
    "ReqInfo": {
      "ResourceType": "VPC",
      "ResourceName": "vpc-01",
      "Tag": {
        "Key": "env",
        "Value": "production"
      }
    }
  }' | jq

응답 예시:

{
  "Key": "env",
  "Value": "production"
}

5.2 Tag 목록 조회 (ListTag)

curl -u "$SPIDER_USERNAME:$SPIDER_PASSWORD" -sX GET \
  'http://localhost:1024/spider/tag?ConnectionName=aws-seoul-config&ResourceType=VPC&ResourceName=vpc-01' | jq

응답 예시:

{
  "tag": [
    {
      "Key": "env",
      "Value": "production"
    },
    {
      "Key": "team",
      "Value": "backend"
    },
    {
      "Key": "Name",
      "Value": "vpc-01"
    }
  ],
  "resourceType": "VPC"
}

5.3 특정 Tag 조회 (GetTag)

curl -u "$SPIDER_USERNAME:$SPIDER_PASSWORD" -sX GET \
  'http://localhost:1024/spider/tag/env?ConnectionName=aws-seoul-config&ResourceType=VPC&ResourceName=vpc-01' | jq

응답 예시:

{
  "Key": "env",
  "Value": "production"
}

5.4 Tag 삭제 (RemoveTag)

curl -u "$SPIDER_USERNAME:$SPIDER_PASSWORD" -sX DELETE 'http://localhost:1024/spider/tag/env' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-seoul-config",
    "ReqInfo": {
      "ResourceType": "VPC",
      "ResourceName": "vpc-01"
    }
  }' | jq

응답 예시:

{
  "Result": "true"
}

5.5 자원 생성 시 Tag 설정 (예: VPC 생성)

자원 생성 API의 요청 Body에 TagList를 포함하여 생성 시점에 Tag를 추가할 수 있다.

curl -u "$SPIDER_USERNAME:$SPIDER_PASSWORD" -sX POST 'http://localhost:1024/spider/vpc' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-seoul-config",
    "ReqInfo": {
      "Name": "vpc-01",
      "IPv4_CIDR": "10.0.0.0/16",
      "SubnetInfoList": [
        {
          "Name": "subnet-01",
          "IPv4_CIDR": "10.0.1.0/24"
        }
      ],
      "TagList": [
        {"Key": "env", "Value": "production"},
        {"Key": "team", "Value": "backend"}
      ]
    }
  }' | jq

6. 주의사항 및 제약사항

6.1 CSP별 Tag 지원 범위가 다름

• CSP마다 Tag를 지원하는 자원의 종류가 다르다 (2절 CSP별 Tag 제공 현황 참조).
• 일부 CSP(Alibaba)는 특정 자원에 대해 자원 생성 시에만 Tag 설정이 가능하며, 생성 후 Tag 관리 API를 통한 추가는 불가하다 (△ 표시).

6.2 Tag 미지원 CSP 및 자원에 대한 처리

• NHN, NCP, KT VPC는 Tagging을 제공하지 않으며, Tag API 호출 시 다음 오류 메시지를 반환한다.
  • "<csp>-config does not support TagHandler"
• Tag 미지원 자원에 대한 API 호출 시 대응:
  1. 자원 생성 요청 시 Tag 설정 요청: 자원은 정상 생성되고, Tag는 추가되지 않음 (Log 출력 없음)
  2. 기존 자원에 Tag 추가 요청: 다음 공통 형식의 에러 메시지 반환 (Error Log 출력)
     • format: [TAG_NOT_SUPPORTED] Tagging is not supported for the resource: {CSP}-{RESOURCE}
     • example: [TAG_NOT_SUPPORTED] Tagging is not supported for the resource: GCP-keypair

6.3 동일 Key 중복 추가 불가

• 동일 자원에 동일 이름의 Key는 중복 추가할 수 없다.
• 이미 존재하는 Key로 AddTag를 호출하면 에러가 반환된다.

6.4 자원 생성 시 Tag 추가 오류 처리

• 자원 생성 시 TagList에 포함된 Tag 중 일부가 실패할 경우:
  1. 생성된 자원은 유지된다.
  2. 생성 성공한 Tag들은 반환 정보의 TagList에 설정되어 반환된다.
  3. 생성 오류 Tag들은 다음 에러 메시지 형식으로 반환된다.
     • "TaggingError: {Key01, Value01}, {Key05, Value05}: CSP 에러 메시지"

6.5 GetTag 및 RemoveTag의 Key는 strict match

• GetTag와 RemoveTag API에서 Key 값은 정확히 일치해야 한다 (부분 일치 불가).

7. API 응답 코드

HTTP Status	설명
200 OK	요청 성공
400 Bad Request	잘못된 요청 (필수 파라미터 누락, 잘못된 자원 타입 등)
404 Not Found	대상 자원을 찾을 수 없음
500 Internal Server Error	서버 내부 오류 또는 CSP API 오류

8. 참고 자료

• CB-Spider REST API 문서 (Swagger)
• Tag and Cloud Driver API (Wiki)
• CSP별 Tag 기능 제공 현황 분석