# Volcano + Kubeflow Trainer 설치 매뉴얼

멀티노드 GPU 분산 학습을 위한 Volcano Scheduler와 Kubeflow Trainer v2 설치 가이드.

## 환경 정보

| 항목 | 값 |
|------|-----|
| Kubernetes | v1.34.3 |
| Helm | v4.0.4 |
| GPU 노드 | InfiniBand 연결 GPU 노드 3대 |
| Volcano | v1.14.0 |
| Kubeflow Trainer | sha-48e7a93 |
| JobSet (의존성) | v0.10.1 |

## 디렉토리 구조

```
kubeflow_trainer_with_volcano/
├── .env                                          # 환경변수 (git 제외)
├── .gitignore
├── README.md                                     # 이 문서
├── charts/
│   ├── volcano/
│   │   └── volcano-1.14.0.tgz                    # Volcano Helm chart
│   └── kubeflow-trainer-0.0.0-sha-48e7a93.tgz    # Kubeflow Trainer Helm chart
├── manifests/
│   └── kubeflow-trainer/
│       └── runtimes/
│           └── runtimes.yaml                     # ClusterTrainingRuntime manifests
└── configs/
    ├── volcano-values.yaml                       # Volcano 커스텀 values
    ├── kubeflow-trainer-values.yaml              # Kubeflow Trainer 커스텀 values
    └── volcano-trainjob-integration.yaml         # Volcano-Trainer 연동 설정 샘플
```

## 사전 요구사항

- Kubernetes 클러스터 (v1.26+)
- Helm v3 이상
- `kubectl` 클러스터 접근 설정 완료
- GPU 노드에 NVIDIA device plugin 설치 완료
- InfiniBand 네트워크 구성 완료
- 클러스터에 기존 Volcano/Kubeflow CRD가 없는 상태
- 컨트롤 플레인 컴포넌트 배치용 노드에 `nodegroup: nd` 라벨 설정 완료

```bash
# 사전 확인
kubectl version
helm version
kubectl get nodes
kubectl get nodes -l nodegroup=nd   # 컨트롤 컴포넌트 배치 노드 확인
nvidia-smi                          # GPU 노드에서 확인
ibstat                              # InfiniBand 상태 확인
```

---

## Task 2: Volcano 설치

Volcano는 Kubernetes를 위한 배치 스케줄링 시스템으로, gang scheduling을 통해 분산 학습 Pod들이 동시에 스케줄링되도록 보장합니다.

### 2.1 네임스페이스 생성

```bash
kubectl create namespace volcano-system
```

### 2.2 Helm으로 Volcano 설치 (로컬 chart 사용)

```bash
helm install volcano charts/volcano/volcano-1.14.0.tgz \
  -n volcano-system \
  -f configs/volcano-values.yaml \
  --wait --timeout 5m
```

주요 커스텀 설정 (`configs/volcano-values.yaml`):
- **scheduler_config_override**: gang scheduling + binpack (GPU 노드 집약 배치) 활성화
- **default_ns**: `nodegroup: nd` — Volcano 컴포넌트를 non-GPU 노드에 배치
- **API rate limits**: 대규모 클러스터용 QPS/Burst 설정

### 2.3 설치 확인

```bash
# Pod 상태 확인 (모두 nodegroup=nd 노드에 배치되어야 함)
kubectl get pods -n volcano-system -o wide

# CRD 확인
kubectl get crd | grep volcano
```

### 2.4 Volcano 삭제 (필요시)

```bash
helm uninstall volcano -n volcano-system
kubectl delete namespace volcano-system
```

---

## Task 3: Kubeflow Trainer 설치

Kubeflow Trainer v2는 TrainJob CRD를 통해 분산 학습 워크로드를 관리합니다.

### 3.1 네임스페이스 생성

```bash
kubectl create namespace kubeflow-trainer
```

### 3.2 Helm으로 Kubeflow Trainer 설치 (로컬 chart 사용)

```bash
helm install kubeflow-trainer charts/kubeflow-trainer-0.0.0-sha-48e7a93.tgz \
  -n kubeflow-trainer \
  -f configs/kubeflow-trainer-values.yaml \
  --wait --timeout 5m
```

주요 커스텀 설정 (`configs/kubeflow-trainer-values.yaml`):
- **manager.nodeSelector**: `nodegroup: nd` — Trainer controller를 non-GPU 노드에 배치
- **jobset.controller.nodeSelector**: `nodegroup: nd` — JobSet controller를 non-GPU 노드에 배치
- **jobset.install**: `true` — JobSet을 함께 설치 (이미 설치되어 있으면 `false`로 변경)

### 3.3 ClusterTrainingRuntime 설치

```bash
kubectl apply -f manifests/kubeflow-trainer/runtimes/runtimes.yaml
```

### 3.4 설치 확인

```bash
# Trainer, JobSet controller 확인 (nodegroup=nd 노드에 배치되어야 함)
kubectl get pods -n kubeflow-trainer -o wide

# CRD 확인
kubectl get crd | grep trainer

# ClusterTrainingRuntime 확인
kubectl get clustertrainingruntimes
```

### 3.5 Kubeflow Trainer 삭제 (필요시)

```bash
kubectl delete -f manifests/kubeflow-trainer/runtimes/runtimes.yaml
helm uninstall kubeflow-trainer -n kubeflow-trainer
kubectl delete namespace kubeflow-trainer
```

---

## Task 4: Volcano ↔ Kubeflow Trainer 연동 설정

Volcano 스케줄러를 Kubeflow TrainJob과 연동하여 gang scheduling, queue 기반 리소스 관리, topology-aware scheduling을 활성화합니다.

> Reference: https://www.kubeflow.org/docs/components/trainer/gang-scheduling/volcano/

### 4.1 연동 설정 적용

`configs/volcano-trainjob-integration.yaml`에 Queue, ClusterTrainingRuntime, 예시 TrainJob이 포함되어 있습니다.

```bash
kubectl apply -f configs/volcano-trainjob-integration.yaml
```

주요 구성 요소:
- **Queue** (`training-queue`): 학습 워크로드의 리소스 풀. `capability`를 실제 클러스터 용량에 맞게 조정 필요
- **ClusterTrainingRuntime** (`torch-distributed-volcano`): `podGroupPolicy.volcano`로 gang scheduling + topology-aware scheduling 자동 적용. PodGroup 수동 생성 불필요
- **Queue 지정**: runtime의 `spec.template.metadata.annotations`에서 설정. TrainJob level에서 override 가능:
  ```yaml
  spec:
    annotations:
      scheduling.volcano.sh/queue-name: "other-queue"
  ```

### 4.2 연동 확인

```bash
# Queue 확인
kubectl get queue training-queue

# ClusterTrainingRuntime 확인
kubectl get clustertrainingruntimes torch-distributed-volcano

# 테스트 TrainJob 상태 확인
kubectl get trainjob

# PodGroup 자동 생성 확인
kubectl get podgroup

# Pod 스케줄러 확인 (schedulerName이 volcano인지)
kubectl get pods -l trainer.kubeflow.org/trainjob-name=<trainjob-name> \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.schedulerName}{"\n"}{end}'
```

---

## 컴포넌트 배치 요약

모든 컨트롤 플레인 컴포넌트는 `nodegroup: nd` 노드에 배치됩니다. GPU 노드에는 학습 Pod만 배치됩니다.

| 컴포넌트 | 네임스페이스 | 배치 노드 | GPU 필요 |
|----------|-------------|-----------|----------|
| Volcano admission | volcano-system | nodegroup: nd | X |
| Volcano controller | volcano-system | nodegroup: nd | X |
| Volcano scheduler | volcano-system | nodegroup: nd | X |
| Trainer controller | kubeflow-trainer | nodegroup: nd | X |
| JobSet controller | kubeflow-trainer | nodegroup: nd | X |
| TrainJob 학습 Pod | default (사용자 지정) | GPU 노드 (InfiniBand) | O |

---

## 검증 체크리스트

- [ ] Volcano Pod 3개 Running (`nodegroup=nd` 노드에 배치 확인)
- [ ] Volcano CRD 생성됨 (jobs, podgroups, queues 등)
- [ ] Kubeflow Trainer controller Running (`nodegroup=nd` 노드에 배치 확인)
- [ ] JobSet controller Running (`nodegroup=nd` 노드에 배치 확인)
- [ ] Kubeflow Trainer CRD 생성됨 (trainjobs, trainingruntimes 등)
- [ ] ClusterTrainingRuntime 목록 확인 (deepspeed-distributed, torch-distributed 등)
- [ ] Training Queue 생성됨
- [ ] 테스트 TrainJob 제출 시 PodGroup 자동 생성 확인
- [ ] 테스트 TrainJob Pod가 Volcano 스케줄러로 스케줄링됨

---

## 트러블슈팅

### Volcano 관련

**Volcano admission webhook 타임아웃**
```bash
kubectl get secret volcano-admission-secret -n volcano-system
kubectl logs -n volcano-system -l app=volcano-admission
```

**Pod가 Pending 상태로 유지**
```bash
# PodGroup 상태 확인 - minMember 충족 여부
kubectl describe podgroup <podgroup-name>
# Queue 리소스 capacity 확인
kubectl get queue training-queue -o yaml
# Volcano scheduler 로그 확인
kubectl logs -n volcano-system -l app=volcano-scheduler
```

### Kubeflow Trainer 관련

**TrainJob이 생성되지 않음**
```bash
kubectl logs -n kubeflow-trainer -l app.kubernetes.io/name=kubeflow-trainer
kubectl describe trainjob <trainjob-name>
```

**ClusterTrainingRuntime을 찾을 수 없음**
```bash
kubectl get clustertrainingruntimes
kubectl apply -f manifests/kubeflow-trainer/runtimes/runtimes.yaml  # 재설치
```

### 연동 관련

**PodGroup이 자동 생성되지 않음**
- ClusterTrainingRuntime에 `podGroupPolicy.volcano: {}` 가 설정되어 있는지 확인
- TrainJob이 올바른 runtimeRef(`torch-distributed-volcano`)를 참조하는지 확인

**TrainJob Pod가 default-scheduler로 스케줄링됨**
- `podGroupPolicy.volcano`가 runtime에 설정되어 있는지 확인
- Volcano가 정상 동작 중인지 확인: `kubectl get pods -n volcano-system`

### 로그 수집

```bash
kubectl logs -n volcano-system -l app=volcano-scheduler --tail=100
kubectl logs -n volcano-system -l app=volcano-controller --tail=100
kubectl logs -n volcano-system -l app=volcano-admission --tail=100
kubectl logs -n kubeflow-trainer -l app.kubernetes.io/name=kubeflow-trainer --tail=100
```