# 2. Kubernetes 기본 설정

EKS 클러스터에 GPU 워크로드를 실행하기 위한 기본 구성요소를 설치합니다. Kubernetes 자체는 GPU를 인식하지 못하므로, NVIDIA 플러그인을 설치해야 합니다.

***

### 2.1 kubeconfig 설정

`kubectl`이 EKS 클러스터와 통신할 수 있도록 연결 정보를 설정합니다.

```bash
aws eks update-kubeconfig --name osmo-eks --region us-west-2
kubectl get nodes
```

**예상 출력 (System 노드 2대가 Ready 상태):**

```
NAME                                       STATUS   ROLES    AGE   VERSION
ip-10-0-1-xxx.us-west-2.compute.internal   Ready    <none>   5m    v1.30.x
ip-10-0-3-xxx.us-west-2.compute.internal   Ready    <none>   5m    v1.30.x
```

{% hint style="info" %}
System 노드 2대만 보이는 것이 정상입니다. GPU 노드는 워크플로 실행 전에 수동으로 스케일업합니다.
{% endhint %}

***

### 2.2 NVIDIA Device Plugin 설치

**왜 필요한가?** Kubernetes는 기본적으로 CPU와 메모리만 관리합니다. GPU를 리소스로 인식하고 Pod에 할당하려면 NVIDIA Device Plugin이 필요합니다. 이 플러그인이 설치되면 `nvidia.com/gpu: 1` 같은 리소스 요청이 가능해집니다.

```bash
kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.14.5/nvidia-device-plugin.yml
```

확인:

```bash
kubectl get daemonset -n kube-system nvidia-device-plugin-daemonset
```

***

### 2.3 NVIDIA RuntimeClass 생성

**왜 필요한가?** 컨테이너 안에서 `nvidia-smi`를 실행하거나 CUDA를 사용하려면, 컨테이너 런타임이 호스트의 GPU 드라이버를 컨테이너에 마운트해줘야 합니다. RuntimeClass를 `nvidia`로 지정하면 이 작업이 자동으로 수행됩니다.

```bash
kubectl apply -f - <<'EOF'
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: nvidia
handler: nvidia
EOF
```

확인:

```bash
kubectl get runtimeclass nvidia
```

***

### Troubleshooting

| 증상                              | 원인                      | 해결                              |
| ------------------------------- | ----------------------- | ------------------------------- |
| `error: You must be logged in`  | kubeconfig 미설정 또는 권한 없음 | `aws eks update-kubeconfig` 재실행 |
| NVIDIA Device Plugin 미동작        | GPU 노드 미존재              | 정상. GPU 노드 scale-up 시 자동 실행됨    |
| `RuntimeClass nvidia not found` | RuntimeClass 미생성        | 2.3 단계 실행                       |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hi-space.gitbook.io/physical-ai-on-aws/physical-ai-on-aws-guide/nvidia-osmo-on-aws/2.-eks-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.