Guide to Using kubectl with CB-Spider Kubeconfig

Language: English | 한국어

Overview

CB-Spider는 멀티 클라우드 Kubernetes 클러스터를 단일 API를 이용하여 생성 및 제어할수 있고,
클러스터 접근할 수 있는 kubeconfig를 제공합니다.
사용자는 kubeconfig 설정으로 kubectl, OpenLens, HeadLamp 등의 Kubernetes 통합 관리 도구를 활용할 수 있습니다.
본 가이드는 Spider가 제공하는 Kubeconfig를 이용하여 kubectl를 활용하는 방법을 제공합니다.

Kubeconfig 타입

Kubeconfig는 CSP별로 포함된 인증 토큰 방식에 따라 다음과 같은 2가지 타입으로 제공됩니다.
- Dynamic Token 타입: kubectl 실행 시 토큰을 자동 갱신하는 exec 기반 kubeconfig
  - kubectl 실행: Spider API 호출 => CSP 토큰 발급 요청 => 토큰 자동 갱신 => Kubernetes 접근
- Static Token 타입: 인증 정보(인증서, 토큰)가 kubeconfig에 직접 포함
  - kubectl 실행: Kubernetes 접근

Dynamic Token 타입(AWS, GCP, NCP)의 경우 Spider API 사용자는 다음 두 가지 인증 옵션을 선택할 수 있습니다:

옵션	처리 방법	Spider 서버 필요
Spider Default (`default`)	Spider Token API 활용 (`~/.cb-spider/.spider-credential` 설정 필요)	O
CSP Native (`KubeconfigType=native`)	CSP 인증 플러그인 활용 (`aws-iam-authenticator`, `gke-gcloud-auth-plugin` 설치 필요)	X

⚠️ NCP(NKS)는 Spider Default만 지원하며, CSP Native 옵션은 제공하지 않습니다.

CSP별 Kubeconfig 타입

CSP	Kubeconfig 방식
AWS (EKS)	Dynamic Token
GCP (GKE)	Dynamic Token
Azure (AKS)	Static Token
Alibaba (ACK)	Static Token
Tencent (TKE)	Static Token
IBM (IKS)	Static Token
NCP (NKS)	Dynamic Token
NHN Cloud	Static Token

방식 비교

비교 항목	Spider Default Dynamic Token	CSP Native Dynamic Token	Static Token
대상 CSP	AWS, GCP, NCP	AWS, GCP	Azure, Alibaba, Tencent, IBM, NHN
Spider 서버 필요	O	X	X
CSP 도구 설치 필요	X	O	X
로컬 CSP 자격증명 필요	X	O	X
토큰 자동 갱신	O	O	X

Kubeconfig 구조

Dynamic Token — Spider Default

users:
- name: aws-dynamic-token
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      interactiveMode: Never
      command: sh
      args:
      - -c
      - ". ~/.cb-spider/.spider-credential && curl -s -u \"$SPIDER_USERNAME:$SPIDER_PASSWORD\" \"http://localhost:1024/spider/cluster/my-cluster/token?ConnectionName=aws-connection\""

sh -c로 credential 파일(~/.cb-spider/.spider-credential)을 소싱한 후 curl로 Spider Token API 호출
kubectl 실행 시마다 자동으로 새 토큰 획득
Spider 서버 접근 필수

Dynamic Token — Spider Default (NCP)

users:
- name: ncp-dynamic-token
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      interactiveMode: Never
      command: sh
      args:
      - -c
      - ". ~/.cb-spider/.spider-credential && curl -s -u \"$SPIDER_USERNAME:$SPIDER_PASSWORD\" \"http://localhost:1024/spider/cluster/my-cluster/token?ConnectionName=ncp-connection\""

AWS/GCP Spider Default 방식과 동일하게 sh -c로 credential 파일을 소싱 후 Spider Token API 호출
CSP Native 옵션 없음 — Spider Default만 지원
Spider 서버 접근 필수

Dynamic Token — CSP Native (AWS)

users:
- name: aws-iam-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      interactiveMode: Never
      command: aws-iam-authenticator
      args:
      - token
      - -i
      - my-cluster

aws-iam-authenticator가 로컬 AWS 자격증명(~/.aws/credentials)으로 STS 토큰 생성
Spider 서버 불필요 — 독립 사용 가능

Dynamic Token — CSP Native (GCP)

users:
- name: gcp-gke-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: gke-gcloud-auth-plugin
      installHint: Install gke-gcloud-auth-plugin for use with kubectl by following
        https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin
      provideClusterInfo: true

gke-gcloud-auth-plugin이 로컬 GCP 자격증명(gcloud auth login)으로 OAuth2 토큰 생성
Spider 서버 불필요 — 독립 사용 가능

Static Token (예: Azure AKS)

users:
- name: clusterAdmin_myResourceGroup_my-aks-cluster
  user:
    client-certificate-data: <Base64-encoded-client-cert>
    client-key-data: <Base64-encoded-client-key>

CSP가 제공한 인증서/토큰이 kubeconfig에 직접 포함
Spider 서버 불필요 — 독립 사용 가능
인증 정보 만료 시 Cluster를 다시 조회하여 재추출

kubectl 실행 구조

Dynamic Token — Spider Default (AWS, GCP, NCP)

kubectl → sh -c → Spider credential 파일 소싱 → curl로 Spider Token API 호출 → 토큰 획득 → K8s 인증

sequenceDiagram
    participant kubectl
    participant sh as sh -c<br/>(credential 파일 소싱)
    participant Spider as CB-Spider<br/>Server
    participant CSP as CSP API<br/>(EKS/GKE/NKS)
    participant K8s as K8s API Server

    kubectl->>sh: kubeconfig exec
    sh->>Spider: curl + Basic Auth<br/>(Token API)
    Spider->>CSP: GenerateClusterToken<br/>(AWS STS / GCP IAM / NCP IAM)
    CSP-->>Spider: Token
    Spider-->>kubectl: Token
    kubectl->>K8s: K8s API call with token
    K8s-->>kubectl: Response

Dynamic Token — CSP Native (AWS, GCP)

kubectl → CSP 인증 플러그인 → 로컬 CSP 자격증명으로 토큰 생성 → K8s 인증 (Spider 서버 경유 불필요)

sequenceDiagram
    participant kubectl
    participant Plugin as CSP 인증 플러그인<br/>(aws-iam-authenticator<br/>gke-gcloud-auth-plugin)
    participant CSP as CSP API<br/>(EKS/GKE)
    participant K8s as K8s API Server

    kubectl->>Plugin: kubeconfig exec
    Plugin->>CSP: Generate token<br/>(로컬 CSP 자격증명 사용)
    CSP-->>Plugin: Token
    Plugin-->>kubectl: Token
    kubectl->>K8s: K8s API call with token
    K8s-->>kubectl: Response

Static Token (Azure, Alibaba, Tencent, IBM, NHN Cloud)

kubeconfig에 인증 정보가 직접 포함 → kubectl이 바로 K8s API 인증 (Spider 서버 경유 불필요)

sequenceDiagram
    participant kubectl
    participant K8s as K8s API Server

    Note over kubectl: 내장 인증 정보<br/>(client-certificate-data,<br/>client-key-data)
    kubectl->>K8s: kubeconfig 내장 인증 정보로<br/>직접 K8s API 호출
    K8s-->>kubectl: Response

Quick Start

1. 사전 준비

# Spider 접속 정보 설정
export SPIDER_USERNAME=${SPIDER_USERNAME:-admin}
export SPIDER_PASSWORD=${SPIDER_PASSWORD:-change-your-password}
export SPIDER_URL="http://localhost:1024/spider"

Spider Default 사용 시, credential 파일을 생성합니다:

mkdir -p ~/.cb-spider
cat > ~/.cb-spider/.spider-credential << 'EOF'
SPIDER_USERNAME=admin
SPIDER_PASSWORD=change-your-password
EOF
chmod 600 ~/.cb-spider/.spider-credential

CSP Native 사용 시, CSP 인증 플러그인을 설치합니다:

# AWS (Ubuntu/Linux)
curl -Lo aws-iam-authenticator https://github.com/kubernetes-sigs/aws-iam-authenticator/releases/download/v0.6.27/aws-iam-authenticator_0.6.27_linux_amd64
chmod +x aws-iam-authenticator && sudo mv aws-iam-authenticator /usr/local/bin/

# GCP (Ubuntu/Linux)
sudo apt-get install -y google-cloud-sdk-gke-gcloud-auth-plugin

2. Kubeconfig 추출

Cluster 조회 API의 응답에 포함된 AccessInfo.Kubeconfig 필드에서 kubeconfig를 추출합니다.

API 상세: Get Cluster (Swagger)

# Spider Default kubeconfig (기본)
curl -s -X GET "$SPIDER_URL/cluster/my-cluster?ConnectionName=aws-connection" \
  -u $SPIDER_USERNAME:$SPIDER_PASSWORD \
  | jq -r '.AccessInfo.Kubeconfig' > ~/.kube/spider-my-cluster.yaml

# CSP Native kubeconfig (AWS/GCP만 해당)
curl -s -X GET "$SPIDER_URL/cluster/my-cluster?ConnectionName=aws-connection&KubeconfigType=native" \
  -u $SPIDER_USERNAME:$SPIDER_PASSWORD \
  | jq -r '.AccessInfo.Kubeconfig' > ~/.kube/spider-my-cluster.yaml

참고: KubeconfigType=native는 AWS(EKS)와 GCP(GKE)에서만 유효 다른 CSP에서는 무시

※ AdminWeb을 통한 추출:

CB-Spider AdminWeb의 Cluster 페이지에서도 Kubeconfig를 확인하고 복사할 수 있습니다.
Cluster 목록의 Access Info → View Details를 클릭하면 Endpoint와 Kubeconfig(YAML)가 표시됩니다.
Dynamic Token CSP(AWS, GCP)의 경우 드롭다운에서 Spider Default 또는 CSP Native를 선택할 수 있습니다.
하단의 복사 버튼을 클릭하여 Kubeconfig를 클립보드에 복사한 후 파일로 저장하세요.

3. kubectl 사용

# 방법 A: --kubeconfig 플래그
kubectl --kubeconfig ~/.kube/spider-my-cluster.yaml get nodes

# 방법 B: KUBECONFIG 환경변수
export KUBECONFIG=~/.kube/spider-my-cluster.yaml
kubectl get nodes
kubectl get pods -A

# 방법 C: 기본 kubeconfig에 병합
cp ~/.kube/config ~/.kube/config.bak
KUBECONFIG=~/.kube/config:~/.kube/spider-my-cluster.yaml kubectl config view --flatten > ~/.kube/config.merged
mv ~/.kube/config.merged ~/.kube/config
kubectl config use-context my-cluster

서버 환경변수 (Dynamic Token 전용)

CB-Spider 서버에서 kubeconfig 생성 시 참조하는 환경변수입니다.

환경변수	설명	기본값
`SERVER_ADDRESS`	kubeconfig Token API URL에 반영되는 Spider 서버 주소	`localhost:1024`

⚠️ Spider 서버가 외부에서 접근되는 환경이라면 SERVER_ADDRESS를 외부 주소로 설정해야 kubeconfig의 Token API URL이 올바르게 생성됩니다.
export SERVER_ADDRESS="10.0.1.50:1024"

Security Notes

kubeconfig 및 credential 파일 권한을 제한하세요:

chmod 600 ~/.kube/spider-my-cluster.yaml
chmod 600 ~/.cb-spider/.spider-credential

kubeconfig 파일을 Git에 커밋하지 마세요.
CSP Native 사용 시 로컬 CSP 자격증명의 IAM 권한을 최소 권한 원칙으로 설정하세요.

Guide to Using kubectl with CB‐Spider Kubeconfig(KR) - cloud-barista/cb-spider GitHub Wiki

Guide to Using kubectl with CB-Spider Kubeconfig

Overview

Kubeconfig 타입

방식 비교

Kubeconfig 구조

Dynamic Token — Spider Default

Dynamic Token — Spider Default (NCP)

Dynamic Token — CSP Native (AWS)

Dynamic Token — CSP Native (GCP)

Static Token (예: Azure AKS)

kubectl 실행 구조

Dynamic Token — Spider Default (AWS, GCP, NCP)

Dynamic Token — CSP Native (AWS, GCP)

Static Token (Azure, Alibaba, Tencent, IBM, NHN Cloud)

Quick Start

1. 사전 준비

2. Kubeconfig 추출

3. kubectl 사용

서버 환경변수 (Dynamic Token 전용)

Security Notes

⚠️ GitHub.com Fallback ⚠️

Guide to Using kubectl with CB‐Spider Kubeconfig(KR) - cloud-barista/cb-spider GitHub Wiki

Guide to Using kubectl with CB-Spider Kubeconfig

Overview

Kubeconfig 타입

방식 비교

Kubeconfig 구조

Dynamic Token — Spider Default

Dynamic Token — Spider Default (NCP)

Dynamic Token — CSP Native (AWS)

Dynamic Token — CSP Native (GCP)

Static Token (예: Azure AKS)

kubectl 실행 구조

Dynamic Token — Spider Default (AWS, GCP, NCP)

Dynamic Token — CSP Native (AWS, GCP)

Static Token (Azure, Alibaba, Tencent, IBM, NHN Cloud)

Quick Start

1. 사전 준비

2. Kubeconfig 추출

3. kubectl 사용

서버 환경변수 (Dynamic Token 전용)

Security Notes

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

⚠️ GitHub.com Fallback ⚠️