From 6b7259035136e98f616229de0ba82093782ea9c4 Mon Sep 17 00:00:00 2001
From: selee <selee@inje-private.com>
Date: Tue, 10 Feb 2026 15:44:49 +0900
Subject: [PATCH] Add resource descriptions to README, set GPU to 8 per node

- README: add Queue/ClusterTrainingRuntime/TrainJob explanations with key options
- README: note single-node testing before multi-node
- Integration: set nvidia.com/gpu to 8 per node, Queue capacity to 24 (3 nodes)
- Integration: TrainJob example set to numNodes: 1 for install testing

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md                                 | 55 +++++++++++++++++------
 configs/volcano-trainjob-integration.yaml | 44 ++++--------------
 2 files changed, 51 insertions(+), 48 deletions(-)

diff --git a/README.md b/README.md
index 9607333..f0c1ef5 100644
--- a/README.md
+++ b/README.md
@@ -158,25 +158,54 @@ Volcano 스케줄러를 Kubeflow TrainJob과 연동하여 gang scheduling, queue
 
 > Reference: https://www.kubeflow.org/docs/components/trainer/gang-scheduling/volcano/
 
-### 4.1 연동 설정 적용
+### 4.1 연동 리소스 개요
 
-`configs/volcano-trainjob-integration.yaml`에 Queue, ClusterTrainingRuntime, 예시 TrainJob이 포함되어 있습니다.
+`configs/volcano-trainjob-integration.yaml`에 아래 3개 리소스가 정의되어 있습니다.
+
+#### Queue — 리소스 풀
+
+학습 워크로드가 사용할 수 있는 총 리소스 상한을 정의합니다. 한 번 생성하면 모든 TrainJob이 공유합니다.
+
+| 옵션 | 설명 |
+|------|------|
+| `weight` | 여러 Queue 간 리소스 배분 비율 (Queue 1개면 무의미) |
+| `reclaimable` | 유휴 리소스를 다른 Queue에 빌려줄 수 있는지 |
+| `capability` | 이 Queue의 최대 리소스 (클러스터 실제 용량에 맞게 조정) |
+
+#### ClusterTrainingRuntime — 학습 환경 템플릿
+
+학습 Pod의 기본 설정을 정의합니다. 한 번 생성하면 여러 TrainJob이 재사용합니다.
+
+| 옵션 | 설명 |
+|------|------|
+| `mlPolicy.torch.numProcPerNode` | 노드당 프로세스 수 (기본값, TrainJob에서 override 가능) |
+| `mlPolicy.numNodes` | 노드 수 (기본값, TrainJob에서 override 가능) |
+| `podGroupPolicy.volcano` | Volcano gang scheduling 활성화. PodGroup 자동 생성 |
+| `podGroupPolicy.volcano.networkTopology` | topology-aware scheduling (InfiniBand 통신 최적화) |
+| `template.metadata.annotations` | Queue 지정 등. TrainJob level에서 override 가능 |
+| `resources.requests/limits` | 노드당 GPU 기본 할당량 (TrainJob에서 override 가능) |
+
+#### TrainJob — 학습 작업 제출
+
+실제 학습을 실행할 때마다 생성합니다. Runtime의 기본값을 상속받고, 필요한 부분만 override합니다.
+
+| 옵션 | 설명 |
+|------|------|
+| `runtimeRef.name` | 사용할 ClusterTrainingRuntime 이름 |
+| `trainer.image` | 학습 컨테이너 이미지 |
+| `trainer.numNodes` | 학습에 사용할 노드 수 (Runtime 기본값 override) |
+| `trainer.numProcPerNode` | 노드당 프로세스 수 (`"auto"`면 GPU 수만큼 자동) |
+| `trainer.resourcesPerNode` | 노드당 리소스 (Runtime 기본값 override) |
+
+> 설치 테스트는 `numNodes: 1`로 단일노드에서 진행합니다. 검증 완료 후 `numNodes`를 늘리면 멀티노드 분산학습이 됩니다.
+
+### 4.2 연동 설정 적용
 
 ```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 연동 확인
+### 4.3 연동 확인
 
 ```bash
 # Queue 확인
diff --git a/configs/volcano-trainjob-integration.yaml b/configs/volcano-trainjob-integration.yaml
index b496ead..d863179 100644
--- a/configs/volcano-trainjob-integration.yaml
+++ b/configs/volcano-trainjob-integration.yaml
@@ -15,10 +15,10 @@ spec:
     # TODO: Adjust based on your cluster capacity
     cpu: "100"
     memory: "512Gi"
-    nvidia.com/gpu: "16"
+    nvidia.com/gpu: "24"
 
 ---
-# 3. ClusterTrainingRuntime with Volcano gang scheduling + topology-aware scheduling
+# 2. ClusterTrainingRuntime with Volcano gang scheduling + topology-aware scheduling
 # podGroupPolicy.volcano를 사용하면 PodGroup이 자동 생성됨 (수동 생성 불필요)
 apiVersion: trainer.kubeflow.org/v1alpha1
 kind: ClusterTrainingRuntime
@@ -29,7 +29,7 @@ metadata:
 spec:
   mlPolicy:
     torch:
-      numProcPerNode: 1
+      numProcPerNode: 8
     numNodes: 1
   # Volcano gang scheduling 활성화 - PodGroup 자동 생성
   podGroupPolicy:
@@ -54,13 +54,14 @@ spec:
                   image: ghcr.io/kubeflow/trainer/torch-runtime:latest
                   resources:
                     requests:
-                      nvidia.com/gpu: "1"
+                      nvidia.com/gpu: "8"
                     limits:
-                      nvidia.com/gpu: "1"
+                      nvidia.com/gpu: "8"
 
 ---
-# 4. Example TrainJob using Volcano-enabled runtime
+# 3. Example TrainJob (설치 테스트용 - 단일노드)
 # podGroupPolicy는 runtime에서 상속되므로 TrainJob에서는 별도 설정 불필요
+# 설치 테스트는 numNodes: 1로 단일노드에서 진행. 멀티노드는 검증 후 numNodes를 늘리면 됨.
 apiVersion: trainer.kubeflow.org/v1alpha1
 kind: TrainJob
 metadata:
@@ -72,35 +73,8 @@ spec:
   trainer:
     # TODO: Replace with your actual training image
     image: docker.io/your-org/your-training-image:latest
-    numNodes: 2
-    numProcPerNode: "auto"
-    resourcesPerNode:
-      requests:
-        nvidia.com/gpu: "4"
-        cpu: "16"
-        memory: "64Gi"
-      limits:
-        nvidia.com/gpu: "4"
-        cpu: "16"
-        memory: "64Gi"
-
----
-# 5. Example TrainJob with queue override at TrainJob level
-# runtime 기본 Queue 대신 다른 Queue를 사용하고 싶을 때
-apiVersion: trainer.kubeflow.org/v1alpha1
-kind: TrainJob
-metadata:
-  name: example-high-priority-training
-  namespace: default
-spec:
-  runtimeRef:
-    name: torch-distributed-volcano
-  annotations:
-    scheduling.volcano.sh/queue-name: "high-priority-queue"
-  trainer:
-    image: docker.io/your-org/your-training-image:latest
-    numNodes: 4
-    numProcPerNode: "auto"
+    numNodes: 1
+    numProcPerNode: "8"
     resourcesPerNode:
       requests:
         nvidia.com/gpu: "8"