> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes

> Kubernetes 클러스터를 CloudThinker에 연결하여 워크로드 분석, 리소스 최적화, 클러스터 운영을 수행합니다

Kubernetes 클러스터를 연결하면 [Kai](/ko/guide/agents/kai)가 워크로드를 분석하고, 리소스를 최적화하며, 클러스터 운영을 관리할 수 있습니다.

Kubernetes는 **클라우드 공급자 자동 검색**(EKS, GKE, AKS의 경우) 또는 자체 관리 클러스터를 위한 클러스터 엔드포인트 정보와 함께 **서비스 어카운트 토큰**을 통해 연결됩니다.

***

## 사전 요구사항

연결 전에 Metrics Server를 설치하세요 — 파드 및 노드 리소스 메트릭에 필요합니다:

```bash theme={null}
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
```

| 구성 요소                  | 용도                                   |
| ---------------------- | ------------------------------------ |
| **Metrics Server**     | 파드 및 노드 리소스 메트릭에 필요                  |
| **kube-state-metrics** | 향상된 클러스터 메트릭 (선택 사항)                 |
| **네트워크 접근**            | CloudThinker가 클러스터 API 서버에 접근 가능해야 함 |

### 지원 플랫폼

| 플랫폼            | 지원                  |
| -------------- | ------------------- |
| **Amazon EKS** | 전체 버전               |
| **Google GKE** | Standard, Autopilot |
| **Azure AKS**  | 전체 버전               |
| **자체 관리**      | Kubernetes 1.24+    |
| **Rancher**    | RKE, RKE2           |
| **OpenShift**  | 4.x                 |

***

## 설정

<Tabs>
  <Tab title="클라우드 공급자 경유 (권장)">
    ### 클라우드 연결에서 자동 검색

    이미 AWS, GCP, Azure를 연결한 경우, 관리형 Kubernetes 클러스터가 자동으로 검색됩니다.

    <Steps>
      <Step title="클라우드 공급자 연결">
        먼저 [AWS](/ko/guide/connections/aws), [GCP](/ko/guide/connections/gcp), 또는 [Azure](/ko/guide/connections/azure) 연결을 설정하세요.
      </Step>

      <Step title="클러스터 자동 검색">
        EKS, GKE, 또는 AKS 클러스터가 CloudThinker에 자동으로 나타납니다. 분석에 사용할 클러스터를 선택하세요. CloudThinker는 활성화된 각 클러스터에 대해 **Connected** 상태를 표시합니다.
      </Step>
    </Steps>
  </Tab>

  <Tab title="직접 Kubeconfig">
    ### 서비스 어카운트를 사용한 수동 설정

    자체 관리 클러스터이거나 클라우드 공급자 연결이 제공하는 것 이상의 추가 접근이 필요한 경우:

    <Steps>
      <Step title="네임스페이스 생성 (선택 사항)">
        전용 네임스페이스를 생성합니다:

        ```yaml theme={null}
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cloudthinker
        ```
      </Step>

      <Step title="서비스 어카운트 생성">
        ```yaml theme={null}
        apiVersion: v1
        kind: ServiceAccount
        metadata:
          name: cloudthinker-readonly
          namespace: cloudthinker
        ```
      </Step>

      <Step title="ClusterRole 생성">
        ```yaml theme={null}
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: cloudthinker-readonly
        rules:
        - apiGroups: [""]
          resources: ["*"]
          verbs: ["get", "list", "watch"]
        - apiGroups: ["apps", "extensions"]
          resources: ["*"]
          verbs: ["get", "list", "watch"]
        - apiGroups: ["autoscaling"]
          resources: ["*"]
          verbs: ["get", "list", "watch"]
        - apiGroups: ["metrics.k8s.io"]
          resources: ["pods", "nodes"]
          verbs: ["get", "list"]
        ```
      </Step>

      <Step title="ClusterRoleBinding 생성">
        ```yaml theme={null}
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: cloudthinker-readonly
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: cloudthinker-readonly
        subjects:
        - kind: ServiceAccount
          name: cloudthinker-readonly
          namespace: cloudthinker
        ```
      </Step>

      <Step title="장기 토큰 생성">
        Kubernetes 1.24부터는 장기 토큰을 위한 Secret을 생성하세요:

        ```yaml theme={null}
        apiVersion: v1
        kind: Secret
        metadata:
          name: cloudthinker-readonly-token
          namespace: cloudthinker
          annotations:
            kubernetes.io/service-account.name: cloudthinker-readonly
        type: kubernetes.io/service-account-token
        ```

        적용:

        ```bash theme={null}
        kubectl apply -f cloudthinker-token-secret.yaml
        ```
      </Step>

      <Step title="토큰 가져오기">
        ```bash theme={null}
        kubectl get secret cloudthinker-readonly-token -n cloudthinker \
          -o jsonpath='{.data.token}' | base64 --decode
        ```
      </Step>

      <Step title="클러스터 정보 가져오기">
        클러스터 엔드포인트를 가져옵니다:

        ```bash theme={null}
        kubectl cluster-info
        ```

        CA 인증서를 추출합니다:

        ```bash theme={null}
        kubectl get secret cloudthinker-readonly-token -n cloudthinker \
          -o jsonpath='{.data.ca\.crt}' | base64 --decode
        ```
      </Step>

      <Step title="CloudThinker에 연결 추가">
        **Connections → Kubernetes**로 이동하여 다음을 입력하세요:

        * 클러스터 API 엔드포인트
        * 서비스 어카운트 토큰
        * CA 인증서 (자체 서명 클러스터의 경우)

        **Connect**를 클릭하세요. CloudThinker가 접근을 검증하고 **Connected** 상태를 표시합니다.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## 연결 세부 정보

CloudThinker가 직접 연결에 사용하는 kubeconfig 형식:

```yaml theme={null}
apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority-data: <base64-encoded-ca-cert>
    server: https://your-cluster-endpoint:6443
  name: your-cluster
contexts:
- context:
    cluster: your-cluster
    user: cloudthinker-readonly
  name: cloudthinker-context
current-context: cloudthinker-context
users:
- name: cloudthinker-readonly
  user:
    token: <your-service-account-token>
```

***

## 필요 권한

### 최소 (읽기 전용)

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cloudthinker-readonly
rules:
- apiGroups: [""]
  resources: ["pods", "nodes", "services", "namespaces", "events", "configmaps"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["autoscaling"]
  resources: ["horizontalpodautoscalers"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["metrics.k8s.io"]
  resources: ["pods", "nodes"]
  verbs: ["get", "list"]
```

### 권장 (전체 분석)

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cloudthinker-full-analysis
rules:
- apiGroups: [""]
  resources: ["pods", "nodes", "services", "namespaces", "events", "configmaps", "secrets", "persistentvolumeclaims", "resourcequotas", "limitranges", "replicationcontrollers"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
  resources: ["jobs", "cronjobs"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["networking.k8s.io"]
  resources: ["ingresses", "networkpolicies"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["autoscaling"]
  resources: ["horizontalpodautoscalers"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["metrics.k8s.io"]
  resources: ["pods", "nodes"]
  verbs: ["get", "list"]
```

<Tip>
  최소 ClusterRole로 시작하고, 더 넓은 기능이 필요한 경우에만 전체 분석 역할로 확장하세요. 절대로 write 동사를 부여하지 마세요 — get, list, watch면 Kai의 모든 기능에 충분합니다.
</Tip>

***

## 에이전트 기능

연결이 완료되면 [Kai](/ko/guide/agents/kai)가 클러스터를 검사하고 최적화할 수 있습니다.

| 기능           | 설명                                    |
| ------------ | ------------------------------------- |
| **리소스 분석**   | 파드 CPU/메모리 사용량, 요청 대비 제한              |
| **노드 상태**    | 노드 상태, 용량, 할당 가능한 리소스                 |
| **워크로드 최적화** | 적정 크기 조정 권고사항, HPA 튜닝                 |
| **문제 해결**    | CrashLoopBackOff, OOMKilled, 보류 중인 파드 |
| **보안 감사**    | RBAC 검토, 파드 보안, 네트워크 정책               |

### 연결 확인

```text theme={null}
@kai check the cluster connection and list all namespaces and node count
```

### 예시 프롬프트

```text theme={null}
@kai analyze pod resource utilization in the production namespace and #report the top CPU and memory consumers
@kai investigate crash loops in the payment service and #recommend a fix
@kai check node resource pressure across the cluster and #alert if any node is near capacity
```

***

## 문제 해결

<Accordion title="클러스터에 연결할 수 없음">
  API 서버 엔드포인트가 인터넷에서 접근 가능한지 확인하세요. 방화벽 규칙과 보안 그룹이 CloudThinker의 IP를 허용하는지 확인하세요. 프라이빗 클러스터의 경우 VPN 또는 배스천 접근을 설정하고 API 서버 인증서가 유효한지 확인하세요.
</Accordion>

<Accordion title="인증 오류">
  서비스 어카운트 토큰이 올바른지 확인하세요. ClusterRoleBinding이 적용되었고 토큰이 만료되지 않았는지 확인하세요. 서비스 어카운트가 올바른 네임스페이스에 존재하는지 확인하세요.
</Accordion>

<Accordion title="메트릭 데이터 없음">
  `kubectl top nodes`를 실행하여 Metrics Server가 설치되어 있는지 확인하세요. Metrics Server 파드가 실행 중이고 `metrics.k8s.io` API가 사용 가능한지 확인하세요.
</Accordion>

<Accordion title="네임스페이스 누락">
  ClusterRole에 네임스페이스 목록 권한이 포함되어 있는지 확인하세요. RBAC이 특정 네임스페이스에 대한 접근을 제한하는지 확인하고 서비스 어카운트 바인딩이 클러스터 전체에 적용되어 있는지 확인하세요.
</Accordion>

***

## 보안

* **최소 권한** — 에이전트가 사용 사례에 필요한 권한만 부여하세요. 읽기 전용으로 시작한 후 필요에 따라 확장하세요.
* **기본 읽기 전용** — 에이전트가 이 연결을 통해 변경 작업을 수행하게 할 것이 아니라면 읽기 전용 자격증명을 사용하세요.
* **자격증명 교체** — 정기 일정에 따라 키와 토큰을 교체하세요. 연결을 업데이트하면 CloudThinker가 새 값을 자동으로 반영합니다.
* **오프보딩 시 취소** — 연결을 삭제하거나 팀원이 퇴사할 때 프로바이더에서 자격증명을 제거하세요.

- **읽기 전용 접근** — CloudThinker 서비스 어카운트에 write 동사를 절대 부여하지 마세요. get, list, watch면 모든 에이전트 기능에 충분합니다.
- **네임스페이스 격리** — 감사 및 취소를 간편하게 하기 위해 서비스 어카운트를 전용 네임스페이스(예: `cloudthinker`)에 보관하세요.

***

## 관련 항목

<CardGroup cols={2}>
  <Card title="Kai 에이전트" icon="dharmachakra" href="/ko/guide/agents/kai">
    Kubernetes 중심 최적화 에이전트
  </Card>

  <Card title="AWS 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/aws.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=45d526a3e9345214c0345f277da2e829" href="/ko/guide/connections/aws" width="24" height="24" data-path="images/icons/aws.svg">
    EKS 자동 검색을 위한 AWS 연결
  </Card>
</CardGroup>