Kubernetes Cluster Management Guide

Language: English | 한국어

1. CB-Spider Kubernetes Cluster 개요

CB-Spider는 연동 대상 클라우드(CSP)가 제공하는 관리형 Kubernetes를
- 동일한 인터페이스를 사용하여 제어할 수 있는 Cluster(Kubernetes Cluster) 제어 기능을 제공합니다.
Kubernetes가 필요한 CB-Spider 사용자(인프라 관리자 또는 서비스 개발자)는 아래 그림과 같이,
- ① CB-Spider 인터페이스를 활용하여 동일한 방법으로
  - 원하는 대상 클라우드에 Kubernetes 인스턴스 생성을 요청할 수 있습니다.
- ② 사용자의 요청은 Spider의 대상 연동 드라이버를 통해서
  - 대상 클라우드의 API를 호출하여 대상 클라우드의 관리형 Kubernetes 인스턴스가 생성됩니다.
- ③ 사용자는 생성된 Kubernetes에 대하여 K8S CLI(kubectl) 또는 API 등의 풍부한 Kubernetes 인터페이스를 사용하여
  - 사용자의 워크로드를 배포 및 관리할 수 있습니다.
  - 또한, OpenLens, Headlamp, Kubesphere 등의 Kubernetes IDE에 연동하여 생성된 Kubernetes의 기능을 편리하게 활용할 수도 있습니다.

[CB-Spider Kubernetes Cluster Overview]

2. CB-Spider Kubernetes Cluster 구성 요소

사용자에 의해 생성된 하나의 Kubernetes 인스턴스는 아래 그림에서 보는 바와 같이 Cluster라고 합니다.
Cluster는 크게 Control Plane, Node Group, Addons 및 Endpoint로 구성됩니다.

[CB-Spider Kubernetes Cluster Components]

컴포넌트별 세부 내용은 다음과 같습니다.

(1) 컨트롤 플레인(Control Plane)

- 컨트롤 플레인은 Cluster의 전체 동작 및 실행을 관장하는 마스터로서의 역할을 담당하는 컴포넌트들의 모임이며, 
- 관리형 Kubernetes의 경우에는 컨트롤 플레인의 관리 주체는 CSP의 Cloud 플랫폼(CloudOS)이며,
- CSP 사용자(=CB-Spider 사용자)는 상태 확인 및 제어를 할 수 없습니다.

(2) 노드 그룹(Node Group)

- 하나의 노드 그룹은 동일한 이미지와 규격으로 생성된 VM들로 구성되며, 
- 하나의 Cluster는 서로 다른 종류의 여러 개의 노드 그룹을 포함할 수 있습니다. 
- 이와 같은 이질적인 노드 그룹 구성을 통하여 하나의 Cluster에서 다양한 종류의 워크로드의 실행 설정이 가능합니다.

(3) 에드온(Addons)

- 에드온은 CNI, DNS 및 Container Resource Monitoring 등으로 
- Cluster 수준의 기능을 제공하는 컴포넌트입니다.
- 다양한 에드온들이 존재하며, 선택적으로 구성하여 활용할 수 있습니다.

(4) 엔드포인트(Endpoint)

- 외부에서 Cluster에 접근할 수 있는 URL을 제공합니다.

3. CB-Spider Kubernetes Cluster 타입

Cluster 생성과 NodeGroup 추가 순서에 따라 다음과 같이 2가지 타입으로 구분됩니다.
(1) Type-I: Cluster 생성 후 NodeGroup 별도 추가/삭제
- 대상 CSP: AWS, Alibaba, Tencent 등
(2) Type-II: 최초 Cluster 생성시 최소 1개 이상의 NodeGroup을 함께 생성, 이후 NodeGroup 추가/삭제 가능
- 대상 CSP: Azure, GCP, IBM, NHN, NCP 등

참고: 노드 그룹 OS로 선택 가능한 이미지 목록
- AWS: NodeGroup 생성시 Image 설정 임시 가이드 (업데이트: PR 1728, 참고: PR 1651)
  - (1) 설정하지 않음 (빈 문자열 또는 "default"):
    - Default AMI Type (AL2023_x86_64_STANDARD)으로 자동 설정 → 표준 x86_64 워크로드에 권장
  - (2) EKS AMI Type 식별자 (예: AL2023_x86_64_STANDARD, AL2023_ARM_64_STANDARD, BOTTLEROCKET_x86_64 등):
    - 변환 없이 AWS EKS에 그대로 전달 → GPU 변형을 포함하여 AMI 타입을 명시적으로 선택할 때 사용
    지원되는 EKS AMI Type 목록
    - AL2023_x86_64_STANDARD
    - AL2023_ARM_64_STANDARD
    - BOTTLEROCKET_ARM_64
    - BOTTLEROCKET_x86_64
    - BOTTLEROCKET_ARM_64_NVIDIA
    - BOTTLEROCKET_x86_64_NVIDIA
    - WINDOWS_CORE_2019_x86_64
    - WINDOWS_FULL_2019_x86_64
    - WINDOWS_CORE_2022_x86_64
    - WINDOWS_FULL_2022_x86_64
  - (3) EC2 Launch Template ID (형식: lt-[17자리 hex], 예: lt-0123456789abcdef0):
    - Launch Template을 수정 없이 직접 참조 → 미리 구성된 EC2 Launch Template을 통해 커스텀 AMI를 지정할 때 사용
    - Launch Template에는 EKS 워커 노드 초기화를 위한 bootstrap UserData가 포함되어야 함
    - cb-spider는 Launch Template을 생성하거나 수정하지 않음
    - EKS용 Launch Template 생성 방법:
      - https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html
  - (4) 원시 EC2 AMI ID (예: ami-0abcdef1234567890) 또는 인식되지 않는 값:
    - 오류 반환 — 자동 AMI ID → EKS AMI Type 매핑 기능이 제거됨 (이전 PR #1651)
    - 커스텀 AMI를 사용하려면, AMI ID와 UserData가 포함된 EC2 Launch Template을 생성한 후 해당 Launch Template ID를 ImageName 값으로 전달 (위 옵션 (3) 참조)
- Tencent: 다음 목록에서 OS Name을 ImageId로 설정
  - https://www.tencentcloud.com/document/product/457/46750

4. CB-Spider Kubernetes Cluster 제공 현황

제공 기능: Cluster 생성/삭제, NodeGroup 추가/삭제, Kubeconfig 제공 등
검증 필요 기능: AutoScaling 설정 변경, Upgrade (전체 또는 일부 CSP 지원, 전체 검증 필요한 기능)
추후 제공 고려: Addons(현재 미구현)

[제공 CSP 목록 및 특이사항]

CSP	특이사항
AWS	• Type-I Cluster (NodeGroup 별도 추가) • 서로 다른 Zone의 2개 이상 Subnet 필요 • Cluster Role, NodeGroup Role 자동 생성
Azure	• Type-II Cluster (최소 1개 NodeGroup 필수) • Subnet CIDR 333 Address 이상 (예: `/23` 이상 권장) • 관련 Role 설정 필요
GCP	• Type-II Cluster (최소 1개 NodeGroup 필수) • Region별 제공 버전이 다름
Alibaba	• Type-I Cluster (NodeGroup 별도 추가)
Tencent	• Type-I Cluster (NodeGroup 별도 추가) • 관련 Role 설정 필요 • 지정된 OS Name 목록에서 이미지 선택
NHN	• Type-II Cluster (최소 1개 NodeGroup 필수)
NCP	• Type-II Cluster (최소 1개 NodeGroup 필수)
IBM	• Type-II Cluster (최소 1개 NodeGroup 필수)

5. CB-Spider Kubernetes Cluster API 및 제공 정보 규격

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

5.1 Kubernetes Cluster 관리 API

# Cluster 생성 및 조회
POST   /spider/cluster                      - Create Cluster
GET    /spider/cluster                      - List Clusters
GET    /spider/cluster/{Name}               - Get Cluster
DELETE /spider/cluster/{Name}               - Delete Cluster

# Cluster 등록/해제 (기존 CSP Cluster 연동)
POST   /spider/regcluster                   - Register Cluster
DELETE /spider/regcluster/{Name}            - Unregister Cluster
POST   /spider/getclusterowner              - Get Cluster Owner VPC

# NodeGroup 관리
POST   /spider/cluster/{Name}/nodegroup     - Add NodeGroup
DELETE /spider/cluster/{Name}/nodegroup/{NodeGroupName} - Remove NodeGroup

# NodeGroup AutoScaling 관리
PUT    /spider/cluster/{Name}/nodegroup/{NodeGroupName}/onautoscaling   - Set NodeGroup AutoScaling
PUT    /spider/cluster/{Name}/nodegroup/{NodeGroupName}/autoscalesize   - Change NodeGroup Scaling

# Cluster Upgrade
PUT    /spider/cluster/{Name}/upgrade       - Upgrade Cluster

# Cluster 목록 조회 (전체)
GET    /spider/allcluster                   - List All Clusters (CB-Spider + CSP)
GET    /spider/allclusterinfo               - List All Cluster Info

# Cluster 통계
GET    /spider/countcluster                 - Count All Clusters
GET    /spider/countcluster/{ConnectionName} - Count Clusters by Connection

# Cluster Token (for kubectl authentication)
GET    /spider/cluster/{Name}/token         - Get Cluster Token

# CSP Cluster 직접 삭제
DELETE /spider/cspcluster/{Id}              - Delete CSP Cluster

5.2 제공 정보 규격

Cluster 정보 (ClusterInfo)

필드	설명	예시
IId	Cluster의 식별자 정보 (NameId, SystemId)	● {Name: "cluster-01", SystemId: "cluster-1234abcd"}
Version	Kubernetes 버전	● "1.30", "1.29", "1.28"
Network	네트워크 정보	● 아래 NetworkInfo 참조
NodeGroupList	NodeGroup 목록	● 아래 NodeGroupInfo 배열 참조
AccessInfo	Cluster 접속 정보	● 아래 AccessInfo 참조
Addons	애드온 정보	● 아래 AddonsInfo 참조
Status	Cluster 상태	● "Creating", "Active", "Inactive", "Updating", "Deleting"
CreatedTime	Cluster 생성 시간	● "2024-03-03T12:34:56Z"
KeyValueList	CSP가 제공하는 추가 정보	● [{Key: "Platform", Value: "eks"}]

Network 정보 (NetworkInfo)

필드	설명	예시
VpcIID	Cluster가 속한 VPC 식별자	● {Name: "vpc-01", SystemId: "vpc-5678efgh"}
SubnetIIDs	Subnet 식별자 목록	● [{Name: "subnet-01", SystemId: "subnet-1234"}]
SecurityGroupIIDs	Security Group 식별자 목록	● [{Name: "sg-01", SystemId: "sg-5678"}]
KeyValueList	CSP가 제공하는 추가 네트워크 정보	● [{Key: "NetworkType", Value: "VPC-Native"}]

NodeGroup 정보 (NodeGroupInfo)

필드	설명	예시
IId	NodeGroup의 식별자 정보	● {Name: "ng-01", SystemId: "ng-1234abcd"}
ImageIID	Node VM의 이미지 식별자	● {Name: "ubuntu-22.04", SystemId: "ami-1234"}
VMSpecName	Node VM의 사양	● "t3.medium", "Standard_D2s_v3"
RootDiskType	Root Disk 타입	● "SSD(gp2)", "Premium SSD"
RootDiskSize	Root Disk 크기 (GB)	● "50", "100"
KeyPairIID	SSH KeyPair 식별자	● {Name: "keypair-01", SystemId: "key-1234"}
OnAutoScaling	AutoScaling 활성화 여부	● true, false
DesiredNodeSize	원하는 노드 개수	● 2, 3, 5
MinNodeSize	최소 노드 개수	● 1, 2
MaxNodeSize	최대 노드 개수	● 3, 5, 10
Status	NodeGroup 상태	● "Creating", "Active", "Inactive", "Updating", "Deleting"
Nodes	Node(VM) 식별자 목록	● [{SystemId: "i-1234"}, {SystemId: "i-5678"}]
KeyValueList	CSP가 제공하는 추가 정보	● [{Key: "ScalingConfig", Value: "Enabled"}]

AccessInfo 정보

필드	설명	예시
Endpoint	Cluster API Server Endpoint URL	● "https://1234.gr7.us-east-1.eks.amazonaws.com"
Kubeconfig	kubectl 접속을 위한 kubeconfig 내용	● "apiVersion: v1\nclusters:\n..."

AddonsInfo 정보

필드	설명	예시
KeyValueList	Addon 정보 목록	● [{Key: "CNI", Value: "aws-vpc-cni"}]

6. CB-Spider Kubernetes Cluster API 및 제공 정보 예시

6.1 Cluster 생성 예시 - Type-I (NodeGroup 제외)

AWS, Alibaba, Tencent 등 Type-I CSP에서 NodeGroup을 제외하고 Cluster만 생성하는 API 호출 예시:

curl -sX POST http://localhost:1024/spider/cluster \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "IDTransformMode": "ON",
    "ReqInfo": {
      "Name": "cluster-01",
      "Version": "1.30",
      "VPCName": "vpc-01",
      "SubnetNames": ["subnet-01", "subnet-02"],
      "SecurityGroupNames": ["sg-01"]
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "cluster-01",
    "SystemId": "arn:aws:eks:us-east-1:123456789012:cluster/cluster-01"
  },
  "Version": "1.30",
  "Network": {
    "VpcIID": {
      "NameId": "vpc-01",
      "SystemId": "vpc-0a1b2c3d4e5f67890"
    },
    "SubnetIIDs": [
      {
        "NameId": "subnet-01",
        "SystemId": "subnet-1234567890abcdef0"
      },
      {
        "NameId": "subnet-02",
        "SystemId": "subnet-0fedcba9876543210"
      }
    ],
    "SecurityGroupIIDs": [
      {
        "NameId": "sg-01",
        "SystemId": "sg-0a1b2c3d4e5f67890"
      }
    ],
    "KeyValueList": []
  },
  "NodeGroupList": [],
  "AccessInfo": {
    "Endpoint": "https://1234ABCD5678EFGH.gr7.us-east-1.eks.amazonaws.com",
    "Kubeconfig": "apiVersion: v1\nclusters:\n- cluster:\n    certificate-authority-data: LS0tLS1CRU...\n    server: https://1234ABCD5678EFGH.gr7.us-east-1.eks.amazonaws.com\n  name: cluster-01\ncontexts:\n- context:\n    cluster: cluster-01\n    user: cluster-01-user\n  name: cluster-01-context\ncurrent-context: cluster-01-context\nkind: Config\npreferences: {}\nusers:\n- name: cluster-01-user\n  user:\n    exec:\n      apiVersion: client.authentication.k8s.io/v1\n      command: /spider/cluster/cluster-01/token\n      args:\n      - --ConnectionName=aws-config01\n"
  },
  "Addons": {
    "KeyValueList": []
  },
  "Status": "Creating",
  "CreatedTime": "2024-03-03T12:34:56Z",
  "KeyValueList": []
}

6.2 Cluster 생성 예시 - Type-II (NodeGroup 포함)

Azure, GCP, IBM, NHN 등 Type-II CSP에서 NodeGroup을 포함하여 Cluster를 생성하는 API 호출 예시:

curl -sX POST http://localhost:1024/spider/cluster \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "azure-config01",
    "IDTransformMode": "ON",
    "ReqInfo": {
      "Name": "cluster-01",
      "Version": "1.29",
      "VPCName": "vpc-01",
      "SubnetNames": ["subnet-01"],
      "SecurityGroupNames": ["sg-01"],
      "NodeGroupList": [
        {
          "Name": "nodegroup-01",
          "ImageName": "ubuntu-22.04",
          "VMSpecName": "Standard_D2s_v3",
          "RootDiskType": "Premium_LRS",
          "RootDiskSize": "50",
          "KeyPairName": "keypair-01",
          "OnAutoScaling": "true",
          "DesiredNodeSize": "2",
          "MinNodeSize": "1",
          "MaxNodeSize": "3"
        }
      ]
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "cluster-01",
    "SystemId": "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/rg-01/providers/Microsoft.ContainerService/managedClusters/cluster-01"
  },
  "Version": "1.29",
  "Network": {
    "VpcIID": {
      "NameId": "vpc-01",
      "SystemId": "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/rg-01/providers/Microsoft.Network/virtualNetworks/vpc-01"
    },
    "SubnetIIDs": [
      {
        "NameId": "subnet-01",
        "SystemId": "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/rg-01/providers/Microsoft.Network/virtualNetworks/vpc-01/subnets/subnet-01"
      }
    ],
    "SecurityGroupIIDs": [
      {
        "NameId": "sg-01",
        "SystemId": "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/rg-01/providers/Microsoft.Network/networkSecurityGroups/sg-01"
      }
    ],
    "KeyValueList": []
  },
  "NodeGroupList": [
    {
      "IId": {
        "NameId": "nodegroup-01",
        "SystemId": "nodegroup-01"
      },
      "ImageIID": {
        "NameId": "ubuntu-22.04",
        "SystemId": "Canonical:0001-com-ubuntu-server-jammy:22_04-lts:latest"
      },
      "VMSpecName": "Standard_D2s_v3",
      "RootDiskType": "Premium_LRS",
      "RootDiskSize": "50",
      "KeyPairIID": {
        "NameId": "keypair-01",
        "SystemId": "keypair-01"
      },
      "OnAutoScaling": true,
      "DesiredNodeSize": 2,
      "MinNodeSize": 1,
      "MaxNodeSize": 3,
      "Status": "Creating",
      "Nodes": [],
      "KeyValueList": []
    }
  ],
  "AccessInfo": {
    "Endpoint": "https://cluster-01-rg-01-12345-abcdef12.hcp.koreacentral.azmk8s.io:443",
    "Kubeconfig": "apiVersion: v1\nclusters:\n- cluster:\n    certificate-authority-data: LS0tLS1CRU...\n    server: https://cluster-01-rg-01-12345-abcdef12.hcp.koreacentral.azmk8s.io:443\n  name: cluster-01\n..."
  },
  "Addons": {
    "KeyValueList": []
  },
  "Status": "Creating",
  "CreatedTime": "2024-03-03T12:34:56Z",
  "KeyValueList": []
}

6.3 Cluster 목록 조회 예시

등록된 Cluster 목록을 조회하는 API 호출 예시:

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

응답 예시:

{
  "cluster": [
    {
      "IId": {
        "NameId": "cluster-01",
        "SystemId": "arn:aws:eks:us-east-1:123456789012:cluster/cluster-01"
      },
      "Version": "1.30",
      "Network": {
        "VpcIID": {
          "NameId": "vpc-01",
          "SystemId": "vpc-0a1b2c3d4e5f67890"
        },
        "SubnetIIDs": [
          {
            "NameId": "subnet-01",
            "SystemId": "subnet-1234567890abcdef0"
          },
          {
            "NameId": "subnet-02",
            "SystemId": "subnet-0fedcba9876543210"
          }
        ],
        "SecurityGroupIIDs": [
          {
            "NameId": "sg-01",
            "SystemId": "sg-0a1b2c3d4e5f67890"
          }
        ],
        "KeyValueList": []
      },
      "NodeGroupList": [
        {
          "IId": {
            "NameId": "nodegroup-01",
            "SystemId": "arn:aws:eks:us-east-1:123456789012:nodegroup/cluster-01/nodegroup-01/abc12345-6789-0123-4567-89abcdef0123"
          },
          "ImageIID": {
            "NameId": "",
            "SystemId": "AL2023_x86_64_STANDARD"
          },
          "VMSpecName": "t3.medium",
          "RootDiskType": "gp3",
          "RootDiskSize": "50",
          "KeyPairIID": {
            "NameId": "keypair-01",
            "SystemId": "keypair-01"
          },
          "OnAutoScaling": true,
          "DesiredNodeSize": 2,
          "MinNodeSize": 1,
          "MaxNodeSize": 3,
          "Status": "Active",
          "Nodes": [
            {
              "NameId": "",
              "SystemId": "i-0a1b2c3d4e5f67890"
            },
            {
              "NameId": "",
              "SystemId": "i-1b2c3d4e5f6789012"
            }
          ],
          "KeyValueList": []
        }
      ],
      "AccessInfo": {
        "Endpoint": "https://1234ABCD5678EFGH.gr7.us-east-1.eks.amazonaws.com",
        "Kubeconfig": "apiVersion: v1\nclusters:\n..."
      },
      "Addons": {
        "KeyValueList": []
      },
      "Status": "Active",
      "CreatedTime": "2024-03-03T12:34:56Z",
      "KeyValueList": []
    }
  ]
}

6.4 Cluster 상세 조회 예시

특정 Cluster의 상세 정보를 조회하는 API 호출 예시:

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

응답 결과는 6.3의 개별 Cluster 정보와 동일

6.5 Kubeconfig를 활용한 kubectl 연동

Cluster 생성 후 Kubeconfig를 활용하여 kubectl로 접근할 수 있습니다.
CB-Spider는 기본적으로 CB-Spider credential-based Kubeconfig를 제공하며, CSP native plugin을 사용하는 Native Kubeconfig도 지원합니다.
Kubeconfig 활용 방법 및 상세 내용은 CB-Spider Kubeconfig 활용 가이드를 참고하세요.

6.6 NodeGroup 추가 예시

기존 Cluster에 새로운 NodeGroup을 추가하는 API 호출 예시:

curl -sX POST http://localhost:1024/spider/cluster/cluster-01/nodegroup \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "IDTransformMode": "ON",
    "ReqInfo": {
      "Name": "nodegroup-02",
      "ImageName": "",
      "VMSpecName": "t3.large",
      "RootDiskType": "gp3",
      "RootDiskSize": "100",
      "KeyPairName": "keypair-01",
      "OnAutoScaling": "true",
      "DesiredNodeSize": "3",
      "MinNodeSize": "2",
      "MaxNodeSize": "5"
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "cluster-01",
    "SystemId": "arn:aws:eks:us-east-1:123456789012:cluster/cluster-01"
  },
  "Version": "1.30",
  "NodeGroupList": [
    {
      "IId": {
        "NameId": "nodegroup-01",
        "SystemId": "arn:aws:eks:us-east-1:123456789012:nodegroup/cluster-01/nodegroup-01/abc12345-6789-0123-4567-89abcdef0123"
      },
      "VMSpecName": "t3.medium",
      "OnAutoScaling": true,
      "DesiredNodeSize": 2,
      "MinNodeSize": 1,
      "MaxNodeSize": 3,
      "Status": "Active",
      "Nodes": [
        {
          "NameId": "",
          "SystemId": "i-0a1b2c3d4e5f67890"
        },
        {
          "NameId": "",
          "SystemId": "i-1b2c3d4e5f6789012"
        }
      ],
      "KeyValueList": []
    },
    {
      "IId": {
        "NameId": "nodegroup-02",
        "SystemId": "arn:aws:eks:us-east-1:123456789012:nodegroup/cluster-01/nodegroup-02/def45678-9012-3456-7890-12345678abcd"
      },
      "VMSpecName": "t3.large",
      "RootDiskType": "gp3",
      "RootDiskSize": "100",
      "OnAutoScaling": true,
      "DesiredNodeSize": 3,
      "MinNodeSize": 2,
      "MaxNodeSize": 5,
      "Status": "Creating",
      "Nodes": [],
      "KeyValueList": []
    }
  ],
  ...
}

6.7 NodeGroup AutoScaling 설정 변경 예시

NodeGroup의 AutoScaling을 활성화/비활성화하는 API 호출 예시:

curl -sX PUT http://localhost:1024/spider/cluster/cluster-01/nodegroup/nodegroup-01/onautoscaling \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "OnAutoScaling": "false"
    }
  }' | jq

응답 예시:

{
  "Result": "true"
}

6.8 NodeGroup Scaling 변경 예시

NodeGroup의 노드 크기를 변경하는 API 호출 예시:

curl -sX PUT http://localhost:1024/spider/cluster/cluster-01/nodegroup/nodegroup-01/autoscalesize \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "DesiredNodeSize": "4",
      "MinNodeSize": "2",
      "MaxNodeSize": "6"
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "nodegroup-01",
    "SystemId": "arn:aws:eks:us-east-1:123456789012:nodegroup/cluster-01/nodegroup-01/abc12345-6789-0123-4567-89abcdef0123"
  },
  "VMSpecName": "t3.medium",
  "OnAutoScaling": true,
  "DesiredNodeSize": 4,
  "MinNodeSize": 2,
  "MaxNodeSize": 6,
  "Status": "Updating",
  "Nodes": [
    {
      "NameId": "",
      "SystemId": "i-0a1b2c3d4e5f67890"
    },
    {
      "NameId": "",
      "SystemId": "i-1b2c3d4e5f6789012"
    }
  ],
  "KeyValueList": []
}

6.9 NodeGroup 제거 예시

Cluster에서 NodeGroup을 제거하는 API 호출 예시:

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

응답 예시:

{
  "Result": "true"
}

6.10 Cluster 버전 업그레이드 예시

Cluster의 Kubernetes 버전을 업그레이드하는 API 호출 예시:

curl -sX PUT http://localhost:1024/spider/cluster/cluster-01/upgrade \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Version": "1.31"
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "cluster-01",
    "SystemId": "arn:aws:eks:us-east-1:123456789012:cluster/cluster-01"
  },
  "Version": "1.31",
  "Status": "Updating",
  ...
}

6.11 Cluster 삭제 예시

Cluster를 삭제하는 API 호출 예시:

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

응답 예시:

{
  "Result": "true"
}

6.12 강제 삭제 예시

Cluster를 강제로 삭제하는 API 호출 예시 (NodeGroup이 있어도 삭제):

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

7. 주의사항 및 제약사항

7.1 Cluster 생성 시 주의사항

사전 준비 리소스: VPC, Subnet, Security Group이 미리 생성되어 있어야 함
Cluster Type 구분:
- Type-I (AWS, Alibaba, Tencent): Cluster 생성 후 NodeGroup 별도 추가
- Type-II (Azure, GCP, IBM, NHN, NCP): Cluster 생성 시 최소 1개 이상의 NodeGroup 필수
Subnet 요구사항:
- AWS: 서로 다른 Zone의 2개 이상 Subnet 필요
- Azure: Subnet CIDR이 333 Address 이상 필요 (예: /24=256개, /23=510개)
Role 설정:
- AWS: Cluster Role, NodeGroup Role 자동 생성됨
- Azure, Tencent: 관련 Role 설정 필요

7.2 NodeGroup 관리 시 주의사항

이미지 선택:
- 일부 CSP는 이미지 선택이 제한되거나 지원하지 않음
- AWS: ImageName 미설정 시 Default AMI Type(AL2023_x86_64_STANDARD) 자동 설정
- Tencent: 지정된 OS Name 목록에서 선택 필요
VMSpec 선택: CSP별로 지원하는 VMSpec이 다름
Disk 설정: CSP별로 지원하는 Disk Type 및 Size가 다름

7.3 Cluster 삭제 시 주의사항

NodeGroup 확인: Cluster 삭제 전에 모든 NodeGroup이 삭제되어야 함 (force=false인 경우)
강제 삭제: force=true 옵션 사용 시 NodeGroup이 있어도 강제 삭제됨 (주의!)
워크로드 확인: Cluster 삭제 전에 실행 중인 Pod 및 워크로드를 확인하고 백업 필요

7.4 Kubeconfig 사용 시 주의사항

CB-Spider는 기본적으로 CB-Spider credential-based Kubeconfig를 제공하며, CSP native plugin을 사용하는 Native Kubeconfig도 지원합니다.
Kubeconfig 활용 방법 및 상세 주의사항은 CB-Spider Kubeconfig 활용 가이드를 참고하세요.
주요 주의사항:
- CB-Spider credential-based Kubeconfig 사용 시 CB-Spider 서버가 실행 중이어야 함
- Native Kubeconfig 사용 시 CSP별 인증 Plugin(aws-iam-authenticator, gke-gcloud-auth-plugin 등) 설치 및 인증 설정 필요

7.5 버전 관리 시 주의사항

Version 형식: CSP별로 버전 형식이 다름
- AWS: "1.30", "1.29" 등
- GCP: "1.29.1-gke.1234567" 등
- NHN: "v1.29.3" 등
Version Upgrade:
- 일부 CSP만 Upgrade API 지원 (전체 검증 필요)
- Major 버전 업그레이드는 지원하지 않을 수 있음
- NodeGroup별로 별도 업그레이드가 필요할 수 있음

7.6 AutoScaling 주의사항

AutoScaling 설정:
- OnAutoScaling=true: 자동으로 노드 개수 조정
- OnAutoScaling=false: 수동으로 노드 개수 조정
노드 개수 조건: DesiredNodeSize는 MinNodeSize와 MaxNodeSize 사이여야 함

7.7 동적 볼륨 프로비저닝

Kubernetes에서 PersistentVolumeClaim(PVC)를 생성하여 동적으로 볼륨을 프로비저닝할 수 있습니다. CSP별로 다음과 같이 설정이 필요합니다:

GCP, Azure: 기본 StorageClass를 제공하므로 바로 PVC 생성 가능
AWS: 적절한 StorageClass를 제공하지 않으므로, 기본 StorageClass를 등록(ebs-sc.yaml)하면 가능
NHN: 적절한 StorageClass를 제공하지 않으므로, 기본 StorageClass를 등록(cinder-sc.yaml)하면 가능
Alibaba: StorageClass를 제공하므로 PVC 생성시 명시하고 20GB 이상 지정 필요
Tencent: 기본 StorageClass를 제공하므로 바로 PVC 생성 가능하나 10GB 이상 지정 필요

Kubernetes Cluster Management Guide(KR) - cloud-barista/cb-spider GitHub Wiki

Kubernetes Cluster Management Guide

1. CB-Spider Kubernetes Cluster 개요

2. CB-Spider Kubernetes Cluster 구성 요소

(1) 컨트롤 플레인(Control Plane)

(2) 노드 그룹(Node Group)

(3) 에드온(Addons)

(4) 엔드포인트(Endpoint)

3. CB-Spider Kubernetes Cluster 타입

(1) Type-I: Cluster 생성 후 NodeGroup 별도 추가/삭제

(2) Type-II: 최초 Cluster 생성시 최소 1개 이상의 NodeGroup을 함께 생성, 이후 NodeGroup 추가/삭제 가능

AWS: NodeGroup 생성시 Image 설정 `임시` 가이드 (업데이트: PR 1728, 참고: PR 1651)

4. CB-Spider Kubernetes Cluster 제공 현황

[제공 CSP 목록 및 특이사항]

5. CB-Spider Kubernetes Cluster API 및 제공 정보 규격

5.1 Kubernetes Cluster 관리 API

5.2 제공 정보 규격

6. CB-Spider Kubernetes Cluster API 및 제공 정보 예시

6.1 Cluster 생성 예시 - Type-I (NodeGroup 제외)

6.2 Cluster 생성 예시 - Type-II (NodeGroup 포함)

6.3 Cluster 목록 조회 예시

6.4 Cluster 상세 조회 예시

6.5 Kubeconfig를 활용한 kubectl 연동

6.6 NodeGroup 추가 예시

6.7 NodeGroup AutoScaling 설정 변경 예시

6.8 NodeGroup Scaling 변경 예시

6.9 NodeGroup 제거 예시

6.10 Cluster 버전 업그레이드 예시

6.11 Cluster 삭제 예시

6.12 강제 삭제 예시

7. 주의사항 및 제약사항

7.1 Cluster 생성 시 주의사항

7.2 NodeGroup 관리 시 주의사항

7.3 Cluster 삭제 시 주의사항

7.4 Kubeconfig 사용 시 주의사항

7.5 버전 관리 시 주의사항

7.6 AutoScaling 주의사항

7.7 동적 볼륨 프로비저닝

8. 참고 자료

⚠️ GitHub.com Fallback ⚠️

Kubernetes Cluster Management Guide(KR) - cloud-barista/cb-spider GitHub Wiki

Kubernetes Cluster Management Guide

1. CB-Spider Kubernetes Cluster 개요

2. CB-Spider Kubernetes Cluster 구성 요소

(1) 컨트롤 플레인(Control Plane)

(2) 노드 그룹(Node Group)

(3) 에드온(Addons)

(4) 엔드포인트(Endpoint)

3. CB-Spider Kubernetes Cluster 타입

(1) Type-I: Cluster 생성 후 NodeGroup 별도 추가/삭제

(2) Type-II: 최초 Cluster 생성시 최소 1개 이상의 NodeGroup을 함께 생성, 이후 NodeGroup 추가/삭제 가능

AWS: NodeGroup 생성시 Image 설정 임시 가이드 (업데이트: PR 1728, 참고: PR 1651)

4. CB-Spider Kubernetes Cluster 제공 현황

[제공 CSP 목록 및 특이사항]

5. CB-Spider Kubernetes Cluster API 및 제공 정보 규격

5.1 Kubernetes Cluster 관리 API

5.2 제공 정보 규격

6. CB-Spider Kubernetes Cluster API 및 제공 정보 예시

6.1 Cluster 생성 예시 - Type-I (NodeGroup 제외)

6.2 Cluster 생성 예시 - Type-II (NodeGroup 포함)

6.3 Cluster 목록 조회 예시

6.4 Cluster 상세 조회 예시

6.5 Kubeconfig를 활용한 kubectl 연동

6.6 NodeGroup 추가 예시

6.7 NodeGroup AutoScaling 설정 변경 예시

6.8 NodeGroup Scaling 변경 예시

6.9 NodeGroup 제거 예시

6.10 Cluster 버전 업그레이드 예시

6.11 Cluster 삭제 예시

6.12 강제 삭제 예시

7. 주의사항 및 제약사항

7.1 Cluster 생성 시 주의사항

7.2 NodeGroup 관리 시 주의사항

7.3 Cluster 삭제 시 주의사항

7.4 Kubeconfig 사용 시 주의사항

7.5 버전 관리 시 주의사항

7.6 AutoScaling 주의사항

7.7 동적 볼륨 프로비저닝

8. 참고 자료

⚠️ **GitHub.com Fallback** ⚠️

AWS: NodeGroup 생성시 Image 설정 `임시` 가이드 (업데이트: PR 1728, 참고: PR 1651)

⚠️ GitHub.com Fallback ⚠️