Language: English | 한국어

• CB-Spider provides Cluster (Kubernetes Cluster) management functionality
  • Allows unified control of managed Kubernetes services provided by connected Cloud Service Providers (CSPs).
• CB-Spider users (infrastructure administrators or service developers) who need Kubernetes can, as shown in the diagram:
  • ① Request Kubernetes instance creation on the desired cloud using the same CB-Spider interface
  • ② User requests are processed through Spider's target driver
    • Calling the target cloud's API to create a managed Kubernetes instance in the target cloud.
  • ③ Users can deploy and manage workloads using rich Kubernetes interfaces such as K8S CLI (kubectl) or APIs
    • Users can also conveniently utilize the created Kubernetes features by integrating with Kubernetes IDEs such as OpenLens, Headlamp, and Kubesphere.

[CB-Spider Kubernetes Cluster Overview]

• A Kubernetes instance created by a user is called a Cluster, as shown in the diagram.
• A Cluster consists mainly of Control Plane, Node Group, Addons, and Endpoint.

[CB-Spider Kubernetes Cluster Components]

• Details of each component are as follows:

  (1) Control Plane

  - The control plane is a collection of components that serve as the master responsible for the overall operation and execution of the Cluster.
  - In the case of managed Kubernetes, the control plane is managed by the CSP's Cloud platform (CloudOS),
  - CSP users (= CB-Spider users) cannot check the status or control it.
  

  (2) Node Group

  - One node group consists of VMs created with the same image and specifications.
  - One Cluster can contain multiple node groups of different types.
  - This heterogeneous node group configuration enables execution settings for various types of workloads in one Cluster.
  

  (3) Addons

  - Addons are components such as CNI, DNS, and Container Resource Monitoring
  - That provide cluster-level functionality.
  - Various addons exist and can be selectively configured and utilized.
  

  (4) Endpoint

  - Provides a URL for external access to the Cluster.
  

• There are two types based on the order of Cluster creation and NodeGroup addition:

• (1) Type-I: Add/Remove NodeGroup separately after Cluster creation

  • Target CSPs: AWS, Alibaba, Tencent, etc.

• (2) Type-II: Create Cluster with at least 1 NodeGroup initially, then add/remove NodeGroups

  • Target CSPs: Azure, GCP, IBM, NHN, NCP, etc.

• Reference: List of images selectable as Node Group OS

  • AWS: Temporary guide for setting Image when creating NodeGroup (Updated: PR 1728, Ref: PR 1651)

    • (1) Not set (empty string or "default"):

      • Automatically set to Default AMI Type (AL2023_x86_64_STANDARD) → Recommended for standard x86_64 workloads

    • (2) EKS AMI Type identifier (e.g. AL2023_x86_64_STANDARD, AL2023_ARM_64_STANDARD, BOTTLEROCKET_x86_64, etc.):

      • Passed through to AWS EKS as-is, without any conversion → Use this to explicitly select the AMI type, including GPU variants

        Supported EKS AMI Type list

        • 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 (format: lt-[17 hex chars], e.g. lt-0123456789abcdef0):

      • The Launch Template is referenced directly without modification → Use this to specify a custom AMI via a pre-configured EC2 Launch Template
      • The Launch Template must include bootstrap UserData for EKS worker node initialization
      • cb-spider does not create or modify the Launch Template
      • How to create a Launch Template for EKS:
        • https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html

    • (4) Raw EC2 AMI ID (e.g. ami-0abcdef1234567890) or any other unrecognized value:

      • Returns an error — automatic AMI ID → EKS AMI Type mapping has been removed (was PR #1651)
      • To use a custom AMI, create an EC2 Launch Template with the AMI ID and UserData, then pass its Launch Template ID as the ImageName value (see option (3) above)

  • Tencent: Set ImageId from OS Name in the following list

    • https://www.tencentcloud.com/document/product/457/46750

• Provided features: Cluster creation/deletion, NodeGroup addition/removal, Kubeconfig provision (kubectl available)
• Features requiring verification: AutoScaling configuration change, Upgrade (supported by all or some CSPs, full verification required)
• Future consideration: Addons (not implemented)

• Users receive Cluster information in JSON format using the following CB-Spider REST API.

# Cluster creation and retrieval
POST   /spider/cluster                      - Create Cluster
GET    /spider/cluster                      - List Clusters
GET    /spider/cluster/{Name}               - Get Cluster
DELETE /spider/cluster/{Name}               - Delete Cluster

# Cluster registration/unregistration (existing CSP Cluster integration)
POST   /spider/regcluster                   - Register Cluster
DELETE /spider/regcluster/{Name}            - Unregister Cluster
POST   /spider/getclusterowner              - Get Cluster Owner VPC

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

# NodeGroup AutoScaling management
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 list retrieval (all)
GET    /spider/allcluster                   - List All Clusters (CB-Spider + CSP)
GET    /spider/allclusterinfo               - List All Cluster Info

# Cluster statistics
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

# Direct CSP Cluster deletion
DELETE /spider/cspcluster/{Id}              - Delete CSP Cluster

• Cluster Information (ClusterInfo)

• Network Information (NetworkInfo)

• NodeGroup Information (NodeGroupInfo)

• AccessInfo Information

• AddonsInfo Information

• API call example for creating a Cluster without NodeGroup on Type-I CSPs such as AWS, Alibaba, Tencent:

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

Response Example:

{
  "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": []
}

• API call example for creating a Cluster with NodeGroup on Type-II CSPs such as Azure, GCP, IBM, NHN:

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

Response Example:

{
  "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": []
}

• API call example for retrieving a list of registered Clusters:

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

Response Example:

{
  "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": []
    }
  ]
}

• API call example for retrieving detailed information of a specific Cluster:

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

Response result is the same as individual Cluster information in 6.3

• After creating a Cluster, you can access it using kubectl with the Kubeconfig.
• CB-Spider provides CB-Spider credential-based Kubeconfig by default and also supports Native Kubeconfig using CSP native plugins.
• For detailed instructions on using Kubeconfig, please refer to CB-Spider Kubeconfig Usage Guide.

• API call example for adding a new NodeGroup to an existing Cluster:

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

Response Example:

{
  "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": []
    }
  ],
  ...
}

• API call example for enabling/disabling AutoScaling of a NodeGroup:

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

Response Example:

{
  "Result": "true"
}

• API call example for changing the node size of a NodeGroup:

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

Response Example:

{
  "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": []
}

• API call example for removing a NodeGroup from a Cluster:

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

Response Example:

{
  "Result": "true"
}

• API call example for upgrading the Kubernetes version of a Cluster:

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

Response Example:

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

• API call example for deleting a Cluster:

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

Response Example:

{
  "Result": "true"
}

• API call example for forcibly deleting a Cluster (deletes even with NodeGroups):

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

• Prerequisite Resources: VPC, Subnet, Security Group must be pre-created
• Cluster Type Classification:
  • Type-I (AWS, Alibaba, Tencent): Add NodeGroup separately after Cluster creation
  • Type-II (Azure, GCP, IBM, NHN, NCP): At least 1 NodeGroup required when creating Cluster
• Subnet Requirements:
  • AWS: 2 or more Subnets in different Zones required
  • Azure: Subnet CIDR must have 333 or more Addresses (e.g., /24=256, /23=510)
• Role Configuration:
  • AWS: Cluster Role, NodeGroup Role automatically created
  • Azure, Tencent: Related Role configuration required

• Image Selection:
  • Some CSPs have limited or no support for image selection
  • AWS: Default AMI Type(AL2023_x86_64_STANDARD) automatically set when ImageName is not set
  • Tencent: Selection required from specified OS Name list
• VMSpec Selection: Supported VMSpec varies by CSP
• Disk Configuration: Supported Disk Type and Size vary by CSP

• NodeGroup Check: All NodeGroups must be deleted before Cluster deletion (when force=false)
• Force Deletion: Forcibly deletes even with NodeGroups when using force=true option (Caution!)
• Workload Check: Check and backup running Pods and workloads before Cluster deletion

• CB-Spider provides CB-Spider credential-based Kubeconfig by default and also supports Native Kubeconfig using CSP native plugins.
• For detailed instructions and precautions on using Kubeconfig, please refer to CB-Spider Kubeconfig Usage Guide.
• Key Precautions:
  • CB-Spider server must be running when using CB-Spider credential-based Kubeconfig
  • CSP-specific authentication plugins (aws-iam-authenticator, gke-gcloud-auth-plugin, etc.) must be installed and configured when using Native Kubeconfig

• Version Format: Version format varies by CSP
  • AWS: "1.30", "1.29", etc.
  • GCP: "1.29.1-gke.1234567", etc.
  • NHN: "v1.29.3", etc.
• Version Upgrade:
  • Upgrade API supported by some CSPs only (full verification required)
  • Major version upgrades may not be supported
  • Separate upgrade may be required for each NodeGroup

• AutoScaling Configuration:
  • OnAutoScaling=true: Automatically adjusts node count
  • OnAutoScaling=false: Manually adjusts node count
• Node Count Condition: DesiredNodeSize must be between MinNodeSize and MaxNodeSize

You can dynamically provision volumes by creating PersistentVolumeClaim (PVC) in Kubernetes. The following settings are required for each CSP:

• GCP, Azure: Default StorageClass provided, PVC can be created immediately
• AWS: No appropriate StorageClass provided, possible by registering default StorageClass (ebs-sc.yaml)
• NHN: No appropriate StorageClass provided, possible by registering default StorageClass (cinder-sc.yaml)
• Alibaba: StorageClass provided, must specify when creating PVC and specify 20GB or more
• Tencent: Default StorageClass provided, PVC can be created immediately but must specify 10GB or more

• CB-Spider User Guide
• CB-Spider REST API Documentation - Cluster Management
• CB-Spider AdminWeb Guide
• CB-Spider Cluster Development and Issue Status