# nccl-perftest Helm Chart

Multi-node NCCL 분산 학습 성능 테스트를 위한 Helm chart.
VGG11 + CIFAR-10 기반 torchrun 분산 학습을 StatefulSet으로 배포한다.

## Prerequisites

- Kubernetes 1.24+
- Helm 3.x
- NVIDIA GPU Operator 설치
- Multus CNI + hostdevice NAD 구성
- InfiniBand 장치 (`/dev/infiniband`)

## Helm Repo (Harbor OCI)

```bash
# Harbor 로그인
helm registry login harbor.inje-private.com -u admin

# Chart pull
helm pull oci://harbor.inje-private.com/infra/nccl-perftest --version 0.1.0
```

## Install

```bash
# 기본 설치 (values.yaml 기본값 사용)
helm install nccl-perftest ./nccl-perftest

# 릴리스 이름 지정
helm install my-release ./nccl-perftest

# OCI 레지스트리에서 직접 설치
helm install nccl-perftest oci://harbor.inje-private.com/infra/nccl-perftest --version 0.1.0
```

## Uninstall

```bash
helm uninstall nccl-perftest
```

## Values 설정

### 커스텀 values 파일 사용

```bash
helm install nccl-perftest ./nccl-perftest -f my-values.yaml
```

### CLI로 개별 값 오버라이드

```bash
# 노드 수 변경 (3노드)
helm install nccl-perftest ./nccl-perftest --set replicaCount=3

# GPU 수 + 노드 수 동시 변경
helm install nccl-perftest ./nccl-perftest \
  --set replicaCount=4 \
  --set resources.gpu=4 \
  --set training.nprocPerNode=4

# 이미지 태그 변경
helm install nccl-perftest ./nccl-perftest --set image.tag="24.12-py3"

# NCCL 디버그 옵션
helm install nccl-perftest ./nccl-perftest \
  --set nccl.ibHCA="mlx5_0\,mlx5_1\,mlx5_2\,mlx5_3" \
  --set nccl.debugFile="/tmp/nccl-%h-%p.log"
```

## Values Reference

### General

| Key | Default | Description |
|-----|---------|-------------|
| `nameOverride` | `"nccl-test"` | K8s 리소스 이름 (StatefulSet, Service, ConfigMap에 공통 적용) |
| `replicaCount` | `2` | 노드(Pod) 수. StatefulSet replicas 및 NNODES 환경변수에 자동 반영 |

### Image

| Key | Default | Description |
|-----|---------|-------------|
| `image.repository` | `nvcr.io/nvidia/pytorch` | 컨테이너 이미지 레지스트리/이름 |
| `image.tag` | `"24.10-py3"` | 이미지 태그 (NGC PyTorch 버전) |
| `image.pullPolicy` | `IfNotPresent` | 이미지 풀 정책 (`Always`, `IfNotPresent`, `Never`) |

### Training

| Key | Default | Description |
|-----|---------|-------------|
| `training.nprocPerNode` | `8` | 노드당 GPU 프로세스 수 (torchrun `--nproc_per_node`) |
| `training.masterPort` | `29500` | 마스터 rendezvous 포트 (torchrun `--rdzv_endpoint`, Service port) |
| `training.batchSize` | `1200` | 글로벌 배치 사이즈 (train_nccl.py `--batch_size` 기본값) |
| `training.epochs` | `90` | 학습 에포크 수 (train_nccl.py `--epoch` 기본값) |
| `training.lr` | `0.01` | 학습률 (train_nccl.py `--lr` 기본값) |

### Resources

| Key | Default | Description |
|-----|---------|-------------|
| `resources.gpu` | `8` | Pod당 nvidia.com/gpu 요청/제한 수 |
| `resources.hostdev` | `2` | Pod당 nvidia.com/hostdev 요청/제한 수 (RDMA NIC) |
| `shmSize` | `"128Gi"` | /dev/shm 공유메모리 크기 (emptyDir sizeLimit) |

### Network (HostDeviceNetwork)

| Key | Default | Description |
|-----|---------|-------------|
| `network.nadName` | `"hostdevice-net"` | HostDeviceNetwork 이름 및 Pod network annotation 값 |
| `network.resourceName` | `"hostdev"` | RDMA 리소스 이름 (HostDeviceNetwork spec.resourceName) |
| `network.networkNamespace` | `"nvidia-network-operator"` | 네트워크 오퍼레이터 네임스페이스 |
| `network.ipam.range` | `"10.200.0.0/28"` | whereabouts IPAM 할당 대역 |
| `network.ipam.exclude` | `["10.200.0.0", "10.200.0.15"]` | IPAM 제외 IP 목록 (네트워크/브로드캐스트 주소) |

### NCCL

| Key | Default | Description |
|-----|---------|-------------|
| `nccl.debug` | `"INFO"` | NCCL_DEBUG 로그 레벨 (`WARN`, `INFO`, `TRACE`) |
| `nccl.debugSubsys` | `"INIT,NET,IB"` | NCCL_DEBUG_SUBSYS 디버그 서브시스템 필터 |
| `nccl.ibDisable` | `0` | NCCL_IB_DISABLE (0=InfiniBand 사용, 1=비활성화) |
| `nccl.socketIfname` | `"net"` | NCCL_SOCKET_IFNAME (OOB 통신용 네트워크 인터페이스) |
| `nccl.ibHCA` | `""` | NCCL_IB_HCA (사용할 IB HCA 목록, 비어있으면 미설정) |
| `nccl.debugFile` | `""` | NCCL_DEBUG_FILE (디버그 로그 파일 경로, 비어있으면 미설정) |

### Volumes

| Key | Default | Description |
|-----|---------|-------------|
| `volumes.dataset.hostPath` | `"/home/ubuntu/cifar-10-batches-py"` | CIFAR-10 데이터셋 호스트 경로 (Pod 내 `/workspace/data/cifar-10-batches-py`에 마운트) |

## 예시: 3노드 4GPU 설정

```yaml
# my-values.yaml
replicaCount: 3

training:
  nprocPerNode: 4
  batchSize: 600

resources:
  gpu: 4
  hostdev: 1

nccl:
  ibHCA: "mlx5_0,mlx5_1"
```

```bash
helm install nccl-3node ./nccl-perftest -f my-values.yaml
```