GPU 자원 선점 사용
Kueue의 WorkloadPriorityClass를 사용하여 GPU 워크로드의 우선순위를 지정하고, 우선순위가 높은 워크로드가 낮은 워크로드의 자원을 선점하도록 설정할 수 있습니다.
선점 개요
GPU 자원의 경합과 선점은 Kueue에서 관리합니다. 하나의 테넌트 네임스페이스는 하나의 ClusterQueue에 대응하며, 선점은 같은 ClusterQueue 안에서만 발생합니다. 다른 테넌트의 워크로드를 선점하거나 다른 테넌트의 워크로드에 의해 선점되지 않습니다.
| 항목 | 설명 |
|---|---|
| 선점 범위 | 같은 테넌트의 ClusterQueue |
| 선점 대상 | 새 워크로드보다 WorkloadPriorityClass 값이 낮은 실행 중 워크로드 |
| 테넌트 간 선점 | 지원하지 않음 |
| LocalQueue 간 입장 순서 | GPU 사용 이력 기반 Fair Sharing 및 LocalQueue weight에 따라 결정 |
테넌트의 ClusterQueue에는 할당된 자원에 맞는 quota와 다음 정책이 적용됩니다.
| 설정 | 값 | 설명 |
|---|---|---|
preemption.withinClusterQueue | LowerPriority | 같은 ClusterQueue 안에서 우선순위가 낮은 워크로드만 선점 |
preemption.reclaimWithinCohort | Never | 다른 테넌트의 워크로드를 선점하지 않음 |
admissionScope.admissionMode | UsageBasedAdmissionFairSharing | LocalQueue 간 GPU 사용 이력이 적은 Queue를 우선 입장 |
queueingStrategy | BestEffortFIFO | 앞선 워크로드가 자원 부족으로 대기 중이어도 실행 가능한 후속 워크로드는 입장 가능 |
선점 조건
다음 조건을 모두 충족하면 Kueue가 우선순위가 낮은 실행 중 워크로드를 내보내고 새 워크로드를 입장시킵니다.
- 새 워크로드가 테넌트 ClusterQueue의 quota 안에 들어가지 못하는 경우
- 같은 ClusterQueue 안에 새 워크로드보다 WorkloadPriorityClass 값이 낮은 실행 중 워크로드가 있는 경우
- 우선순위가 낮은 워크로드를 내보내면 새 워크로드가 quota 안에 들어가는 경우
우선순위가 같거나 높은 워크로드는 선점되지 않습니다. 선점할 수 있는 워크로드가 없으면 새 워크로드는 자원을 사용할 수 있을 때까지 Queue에서 대기합니다.
우선순위 클래스
다음 WorkloadPriorityClass를 사용할 수 있습니다.
| 이름 | 값 | 용도 |
|---|---|---|
low | 100 | 선점되어도 되는 낮은 우선순위의 작업 |
normal | 500 | 일반 작업에 사용하는 기본 우선순위 |
high | 1000 | 높은 우선순위가 필요한 작업 |
critical | 1500 | 즉시 실행해야 하는 긴급 작업 |
high와 critical은 운영상 필요한 경우에만 사용하세요. 우선순위를 높여도 테넌트에 할당된 quota를 초과하여 사용할 수 없으며, 같은 테넌트에서 실행 중인 낮은 우선순위의 워크로드가 선점될 수 있습니다.
워크로드에 우선순위 지정
워크로드의 kueue.x-k8s.io/priority-class 라벨에 사용할 우선순위 클래스 이름을 입력합니다.
TrainJob은 metadata.labels에 라벨을 추가합니다.
apiVersion: trainer.kubeflow.org/v1alpha1
kind: TrainJob
metadata:
name: finetune-01
namespace: <사용자 namespace>
labels:
kueue.x-k8s.io/queue-name: training
kueue.x-k8s.io/priority-class: high
spec:
runtimeRef:
apiGroup: trainer.kubeflow.org
kind: ClusterTrainingRuntime
name: torch-distributed
trainer:
numNodes: 2
numProcPerNode: 8
resourcesPerNode:
requests:
nvidia.com/gpu: "8"
limits:
nvidia.com/gpu: "8"
Deployment, LeaderWorkerSet, DynamoGraphDeployment와 같이 Pod 단위로 Kueue가 관리하는 워크로드는 Pod 템플릿의 metadata.labels에 라벨을 추가합니다.
kueue.x-k8s.io/queue-name에는 사용자 네임스페이스에 생성한 LocalQueue 이름을 입력합니다. 워크로드를 생성할 때 Queue와 우선순위 라벨을 함께 지정하는 것을 권장합니다.
테넌트 전용 우선순위 클래스 생성
기본 우선순위 사이에 별도의 등급이 필요하면 사용자 네임스페이스에 CustomWorkloadPriorityClass를 생성합니다. 플랫폼에서 같은 이름의 WorkloadPriorityClass를 생성합니다.
이름은 <사용자 namespace>-<우선순위 이름> 형식으로 입력합니다. 생성한 이름은 워크로드의 kueue.x-k8s.io/priority-class 라벨에 동일하게 입력합니다.
apiVersion: kakaocloud.io/v1alpha1
kind: CustomWorkloadPriorityClass
metadata:
name: <사용자 namespace>-urgent
namespace: <사용자 namespace>
spec:
value: 1200
description: 분기 마감 전 재학습
다음 명령어를 실행하여 생성 상태를 확인합니다.
kubectl get cwpc -n <사용자 namespace>
READY가 True이면 사용할 수 있습니다. 같은 이름의 WorkloadPriorityClass가 이미 있으면 READY가 False, reason이 NameConflict로 표시됩니다. 이 경우 다른 이름으로 다시 생성합니다.
metadata:
labels:
kueue.x-k8s.io/queue-name: training
kueue.x-k8s.io/priority-class: <사용자 namespace>-urgent
CustomWorkloadPriorityClass를 삭제하면 연결된 WorkloadPriorityClass도 함께 삭제됩니다. 삭제된 클래스를 참조하는 새 워크로드는 WorkloadPriorityClassNotFound 경고와 함께 입장하지 못하므로, 삭제하기 전에 해당 클래스를 참조하는 워크로드가 없는지 확인하세요.
LocalQueue 간 입장 순서 조정
같은 테넌트 안에서 팀별로 LocalQueue를 생성하여 워크로드의 입장 순서를 조정할 수 있습니다. 모든 LocalQueue는 테넌트의 ClusterQueue를 사용해야 하므로 spec.clusterQueue에는 사용자 네임스페이스와 같은 값을 입력합니다.
apiVersion: kueue.x-k8s.io/v1beta2
kind: LocalQueue
metadata:
name: training
namespace: <사용자 namespace>
spec:
clusterQueue: <사용자 namespace>
fairSharing:
weight: "2"
fairSharing.weight 값이 클수록 GPU 사용 이력이 같은 조건에서 먼저 입장합니다. 이 값은 LocalQueue의 입장 순서에만 영향을 주며, 워크로드의 선점 여부는 WorkloadPriorityClass 값으로 결정됩니다.
LocalQueue를 생성하고 워크로드에 적용하는 방법은 Queue와 Scheduler 사용을 참고하세요.
선점된 워크로드 확인
다음 명령어를 실행하여 Kueue Workload의 상태를 확인합니다.
kubectl get workloads -n <사용자 namespace>
kubectl describe workload -n <사용자 namespace> <Workload 이름>
선점된 Workload에는 다음 조건이 표시됩니다.
Evicted가True,reason이PreemptedPreempted조건의reason이InClusterQueuemessage에 선점한 워크로드의 UID와 JobUID 표시
message에 표시된 JobUID를 사용하여 선점한 워크로드를 확인할 수 있습니다.
kubectl get workloads -n <사용자 namespace> -l kueue.x-k8s.io/job-uid=<JobUID>
선점된 TrainJob은 Suspend 상태로 변경되며, Queue에서 다시 자원을 기다립니다.
주의 사항
- TrainJob에
scheduling.volcano.sh/queue-nameannotation 또는kai.scheduler/queue라벨을 추가하지 마세요. TrainJob의 자원 통제와 선점은 Kueue가 담당하며, 해당 값을 추가하면 생성이 거부됩니다. - WorkloadPriorityClass는 Pod의 PriorityClass와 별개입니다. 워크로드의 선점 순서는 WorkloadPriorityClass 값으로 결정됩니다.
- 우선순위를 높여도 테넌트에 할당된 quota를 초과하여 사용할 수 없습니다. 선점은 같은 테넌트의 quota 안에서 워크로드의 실행 순서를 조정합니다.
Gang Scheduling
Gang Scheduling 개요
분산 학습이나 멀티노드 서빙은 여러 Pod가 동시에 실행되어야 합니다. 일부 Pod만 먼저 실행되면 나머지를 기다리는 동안 GPU를 점유할 수 있으므로, 필요한 Pod를 모두 한 번에 배치할 수 있을 때 작업을 시작하는 방식을 Gang Scheduling이라고 합니다.
이 클러스터에서 역할은 다음과 같이 나뉩니다.
| 단계 | 담당 | 하는 일 |
|---|---|---|
| admission | Kueue | 테넌트 quota 안에 들어가는지 판단합니다. Job과 TrainJob은 입장 전까지 suspend 상태이므로 Pod가 생성되지 않습니다. Deployment, LeaderWorkerSet, DynamoGraphDeployment는 Pod가 생성되지만 scheduling gate에 묶여 배치되지 않습니다. |
| placement | Volcano 또는 KAI Scheduler | Kueue를 통과한 모든 워크로드의 Pod를 한 번에 노드에 배치합니다. 자리가 부족하면 모두 대기합니다. |
TrainJob, LLMInferenceService, DynamoGraphDeployment를 사용하면 gang 여부와 스케줄러는 플랫폼 설정을 따르므로 고객이 PodGroup을 만들 필요가 없습니다.
Kubernetes Job, JobSet, Deployment, Pod를 직접 사용하면 플랫폼이 gang을 만들지 않으므로 고객이 gang 그룹을 직접 선언해야 합니다.
방법은 아래 "직접 Gang 설정 (Job, JobSet, Deployment, Pod)" 절에 있습니다.
| 워크로드 | 스케줄러 | Gang 단위 | 고객이 지정하는 것 |
|---|---|---|---|
| TrainJob | Runtime에 따라 KAI 또는 Volcano | TrainJob의 모든 노드 Pod | runtimeRef로 Runtime 선택 |
| LLMInferenceService (worker 있음) | Volcano | LWS 그룹(leader + worker) 하나 prefill Deployment는 Gang 밖 | schedulerName: volcano-scheduler |
| DynamoGraphDeployment | KAI (Grove PodGang) | DGD 전체. 각 컴포넌트의 minAvailable만큼이 한 Gang이며, 멀티노드 worker는 leader 1개와 worker(nodeCount - 1)개 Pod로 구성 | schedulerName: kai-scheduler, kai.scheduler/enabled 라벨 |
| Job, JobSet, Deployment, Pod(직접 설정) | Volcano 또는 KAI 중 선택 | 직접 만든 PodGroup 또는 Job/JobSet의 batch-min-member | PodGroup 또는 gang 어노테이션을 직접 작성. 아래 "직접 Gang 설정" 절 참고 |
TrainJob
TrainJob은 spec.runtimeRef로 지정하는 ClusterTrainingRuntime이 스케줄러와 gang 정책을 결정합니다.
플랫폼이 제공하는 Runtime은 다음과 같습니다.
| Runtime 이름 | 스케줄러 | 배치 정책 |
|---|---|---|
| torch-distributed-kai-scheduler | KAI | 같은 스위치에 모아 배치, 자리가 없으면 스위치에 걸쳐서라도 배치 |
| torch-distributed-volcano | Volcano | 네트워크 토폴로지 soft 모드, 같은 스위치에 모으려 하되 안되면 분산 배치 |
| torch-distributed-volcano-hard | Volcano | 네트워크 토폴로지 hard 모드, highestTierAllowed: 1. 이 클러스터의 HyperNode는 tier 1 하나이며, 같은 스위치 안에 전부 배치할 수 있을 때만 실행하고 그렇지 않으면 계속 대기 |
세 Runtime 모두 numNodes개의 Pod를 하나의 PodGroup으로 묶어, 모두 배치할 수 있을 때만 시작합니다. 일부 Pod만 먼저 실행되지는 않습니다.
apiVersion: trainer.kubeflow.org/v1alpha1
kind: TrainJob
metadata:
name: pretrain-01
namespace: kbm-g-np-example
labels:
kueue.x-k8s.io/queue-name: training
kueue.x-k8s.io/priority-class: normal
spec:
runtimeRef:
apiGroup: trainer.kubeflow.org
kind: ClusterTrainingRuntime
name: torch-distributed-kai-scheduler
trainer:
numNodes: 4
numProcPerNode: 8
resourcesPerNode:
requests:
cpu: "8"
memory: 32Gi
nvidia.com/gpu: "8"
limits:
cpu: "8"
memory: 32Gi
nvidia.com/gpu: "8"
LLMInferenceService (멀티노드 서빙)
spec.worker가 있는 LLMInferenceService는 LeaderWorkerSet으로 배포되고, leader와 worker가 하나의 gang으로 묶입니다. LWS 컨트롤러가 그룹마다 Volcano PodGroup을 만들며, 그룹 크기(Pod 수)는 parallelism.data와 parallelism.dataLocal로 결정됩니다. parallelism.data는 데이터 병렬(DP) rank 수이고, dataLocal은 Pod 하나가 맡는 DP rank 수입니다. parallelism.tensor는 DP rank 하나에서 사용하는 GPU 수(TP)입니다. TP는 Pod 안에서만 이루어지며 Pod 사이를 넘지 않습니다.
prefill도 같은 규칙을 따릅니다. spec.prefill.worker를 지정하면 prefill용 LeaderWorkerSet이 별도로 만들어져 자체 그룹 안에서 gang이 됩니다. 지정하지 않으면 Deployment로 만들어져 gang 대상이 아닙니다. 어느 경우든 prefill과 decode는 서로 다른 LWS 또는 Deployment이므로 둘을 묶는 gang은 없습니다.
Pod가 Volcano로 배치되도록 spec.template, spec.worker, spec.prefill.template에 schedulerName: volcano-scheduler를 지정합니다. 멀티노드 prefill이면 spec.prefill.worker에도 지정합니다.
apiVersion: serving.kserve.io/v1alpha2
kind: LLMInferenceService
metadata:
name: glm-5-3
namespace: kbm-g-np-example
labels:
kueue.x-k8s.io/queue-name: serving
kueue.x-k8s.io/priority-class: high
spec:
replicas: 1
parallelism:
tensor: 8
data: 2
dataLocal: 1
template:
schedulerName: volcano-scheduler
worker:
schedulerName: volcano-scheduler
prefill:
replicas: 1
parallelism:
tensor: 8
template:
schedulerName: volcano-scheduler
위 예제에서 decode는 DP rank 2개(data: 2)이고 Pod 하나가 DP rank 1개(dataLocal: 1)를 맡으므로 LWS 그룹은 Pod 2개(leader 1개와 worker 1개)입니다. 각 Pod는 TP 8로 GPU 8장을 사용하므로 decode 전체에는 GPU 16장이 필요합니다. 두 Pod는 Volcano PodGroup 하나(minMember: 2)로 묶여 함께 스케줄됩니다. 이 예제의 prefill은 spec.prefill.worker가 없어 Deployment Pod 1개(TP 8, GPU 8장)로 만들어지며 gang 대상이 아닙니다. 따라서 gang은 decode 그룹 안에서만 성립하고, prefill과 decode가 같은 시점에 배치되는 것은 보장되지 않습니다.
spec.worker는 KServe의 decode worker 템플릿에 strategic merge 방식으로 병합됩니다. 템플릿의 worker 컨테이너에는 probe가 없으므로, 예를 들어 startupProbe.failureThreshold만 적으면 handler(httpGet 등)가 없는 probe가 만들어져 API 서버가 worker Pod 생성을 거부합니다. worker가 없으면 LWS 그룹(minMember: 2)이 채워지지 않아 leader도 Pending 상태로 남습니다. 템플릿에 없는 객체를 덮어쓸 때는 필드 하나가 아니라 객체 전체를 지정해야 합니다.
DynamoGraphDeployment (멀티노드 서빙)
Grove는 Frontend를 포함한 DGD의 모든 컴포넌트를 하나의 PodGang으로 묶고 KAI가 배치합니다. 각 컴포넌트에서 minAvailable에 지정한 수만큼의 Pod가 gang에 포함되므로, Frontend, prefill, decode가 함께 배치될 자리를 확보해야 스케줄됩니다. multinode.nodeCount가 없는 단일 노드 컴포넌트도 이 규칙을 따릅니다. worker에 multinode.nodeCount를 지정하면 leader 1개와 worker(nodeCount - 1)개 Pod로 전개되어 같은 gang에 포함됩니다. Pod 템플릿에는 kai.scheduler/enabled: "true" 라벨과 schedulerName: kai-scheduler를 지정합니다.
apiVersion: nvidia.com/v1beta1
kind: DynamoGraphDeployment
metadata:
name: glm-5-3-nodecount4
namespace: kbm-g-np-example
spec:
backendFramework: vllm
components:
- name: VllmWorker
type: worker
replicas: 1
multinode:
nodeCount: 4
podTemplate:
metadata:
labels:
kai.scheduler/enabled: "true"
kueue.x-k8s.io/queue-name: serving
kueue.x-k8s.io/priority-class: high
spec:
schedulerName: kai-scheduler
nodeCount는 모델 하나가 노드 한 대에 들어가지 않을 때만 사용합니다. 한 노드에 들어가는 모델은 replicas로 복제하는 편이 단순하고 장애에 강합니다. Pod가 서로 다른 노드에 배치되는지는 Pod당 GPU 요청량(예: 8장)에 따라 결정되며, nodeCount 자체가 노드 분산을 강제하지는 않습니다.
멀티노드 worker의 resources, image, args를 변경해도 Dynamo operator가 롤링 업데이트를 직접 수행하지 않습니다. RollingUpdateNotSupported 경고와 함께 PodCliqueSet 템플릿만 갱신됩니다. 실제 교체는 Grove의 기본 전략인 RollingRecreate가 PCSG replica 단위로 삭제한 뒤 다시 생성합니다. replica가 1개인 멀티노드 worker는 교체 중 전체가 중단되므로 무중단 업데이트가 아닙니다. 교체가 지연되면 gang이 채워지지 않을 수 있습니다. 운영 환경에서는 DGD를 삭제한 뒤 다시 만드는 편이 결과를 예측하기 쉽습니다.
직접 Gang 설정 (Job, JobSet, Deployment, Pod)
TrainJob, LLMInferenceService, DynamoGraphDeployment 대신 Kubernetes Job, JobSet, Deployment, 단일 Pod로 워크로드를 직접 만들 때도 gang scheduling을 사용할 수 있습니다. 이 경우 gang 그룹을 직접 선언하고, Volcano와 KAI 중 하나를 선택해 워크로드 안에서 혼용하지 않습니다.
어느 쪽을 선택하든 Kueue의 입장 절차는 동일합니다. Job, JobSet, Deployment, Pod에는 모두 kueue.x-k8s.io/queue-name 라벨이 필요합니다. 라벨이 없으면 Pod가 생성되지 않거나 스케줄링 게이트에 걸려 시작하지 않습니다.
Volcano로 직접 설정
PodGroup을 먼저 만들고 같은 gang에 속할 Pod 템플릿에 scheduling.k8s.io/group-name 어노테이션으로 PodGroup 이름을 지정합니다. schedulerName은 volcano-scheduler로 설정합니다. 이 클러스터에서는 Volcano queue를 사용하지 않으므로 spec.queue는 지정하지 않습니다.
apiVersion: scheduling.volcano.sh/v1beta1
kind: PodGroup
metadata:
name: allreduce-test
namespace: kbm-g-np-example
spec:
minMember: 4
---
apiVersion: batch/v1
kind: Job
metadata:
name: allreduce-test
namespace: kbm-g-np-example
labels:
kueue.x-k8s.io/queue-name: training
kueue.x-k8s.io/priority-class: normal
spec:
parallelism: 4
completions: 4
completionMode: Indexed
template:
metadata:
annotations:
scheduling.k8s.io/group-name: allreduce-test
spec:
schedulerName: volcano-scheduler
restartPolicy: Never
containers:
- name: main
image: pytorch/pytorch:2.7.1-cuda12.8-cudnn9-runtime
command: ["sleep", "600"]
resources:
requests:
cpu: "8"
memory: 32Gi
nvidia.com/gpu: "8"
limits:
cpu: "8"
memory: 32Gi
nvidia.com/gpu: "8"
minMember는 동시에 배치되어야 하는 Pod 수이며, 보통 parallelism과 같게 설정합니다. Deployment나 단일 Pod도 같은 방식으로 Pod 템플릿에 어노테이션과 schedulerName을 지정할 수 있습니다.
어노테이션 없이 schedulerName: volcano-scheduler만 지정하면 Volcano가 Pod마다 minMember: 1인 PodGroup을 자동으로 만듭니다. 이 경우 Gang Scheduling이 적용되지 않으므로 어노테이션을 반드시 지정합니다.
KAI로 직접 설정
Job이나 JobSet은 PodGroup을 직접 만들지 않습니다. 리소스에 kai.scheduler/batch-min-member 어노테이션으로 Gang의 최소 크기를 지정하면 KAI가 PodGroup을 만듭니다. Pod 템플릿에는 kai.scheduler/enabled: "true"와 kai.scheduler/queue: default-queue 라벨, schedulerName: kai-scheduler를 지정합니다.
apiVersion: batch/v1
kind: Job
metadata:
name: allreduce-test
namespace: kbm-g-np-example
labels:
kueue.x-k8s.io/queue-name: training
kueue.x-k8s.io/priority-class: normal
annotations:
kai.scheduler/batch-min-member: "4"
spec:
parallelism: 4
completions: 4
completionMode: Indexed
template:
metadata:
labels:
kai.scheduler/enabled: "true"
kai.scheduler/queue: default-queue
spec:
schedulerName: kai-scheduler
restartPolicy: Never
containers:
- name: main
image: pytorch/pytorch:2.7.1-cuda12.8-cudnn9-runtime
command: ["sleep", "600"]
resources:
requests:
cpu: "8"
memory: 32Gi
nvidia.com/gpu: "8"
limits:
cpu: "8"
memory: 32Gi
nvidia.com/gpu: "8"
Job은 kai.scheduler/batch-min-member가 없으면 KAI가 minMember: 1인 PodGroup을 만들어 Gang Scheduling이 적용되지 않습니다. 어노테이션을 반드시 지정하고, 값은 보통 parallelism과 같게 설정합니다.
JobSet에서는 어노테이션 위치에 따라 의미가 다릅니다. JobSet의 metadata.annotations는 동시에 시작해야 하는 replicatedJob 수를 지정하고, replicatedJobs[].template.metadata.annotations는 해당 replicatedJob에서 동시에 배치해야 하는 Pod 수를 지정합니다. JobSet은 어노테이션이 없으면 Job의 parallelism을 기본값으로 사용합니다.
Deployment나 단일 Pod처럼 Job이 아닌 리소스를 Gang으로 묶으려면 PodGroup을 직접 만들고 Pod를 연결합니다. Deployment의 각 Pod에 별도의 PodGroup이 생성되지 않도록 리소스에 kai.scheduler/skip-podgrouper: "true" 어노테이션을 지정합니다. 그런 다음 Pod 템플릿의 pod-group-name 어노테이션에 PodGroup 이름을 지정합니다.
apiVersion: scheduling.run.ai/v2alpha2
kind: PodGroup
metadata:
name: serving-group
namespace: kbm-g-np-example
spec:
minMember: 2
queue: default-queue
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: serving-group
namespace: kbm-g-np-example
annotations:
kai.scheduler/skip-podgrouper: "true"
spec:
replicas: 2
selector:
matchLabels:
app: serving-group
template:
metadata:
labels:
app: serving-group
kai.scheduler/enabled: "true"
kueue.x-k8s.io/queue-name: serving
kueue.x-k8s.io/priority-class: normal
annotations:
pod-group-name: serving-group
spec:
schedulerName: kai-scheduler
containers:
- name: main
image: docker.io/vllm/vllm-openai:v0.28.0
resources:
requests:
cpu: "8"
memory: 32Gi
nvidia.com/gpu: "8"
limits:
cpu: "8"
memory: 32Gi
nvidia.com/gpu: "8"
상태 확인
Pending 이 길어지면 먼저 Kueue 입장 단계인지, 스케줄러 배치 단계인지 구분합니다.
kubectl get workloads -n kbm-g-np-example
kubectl describe workload -n kbm-g-np-example <workload-name>
Workload의 Admitted가 False이면 테넌트 quota 부족으로 Kueue에서 대기 중입니다. Job과 TrainJob은 아직 Pod가 생성되지 않습니다. Deployment, LeaderWorkerSet, DynamoGraphDeployment의 Pod는 SchedulingGated 상태로 표시됩니다.
Admitted가 True인데 Pod가 Pending이면 Gang 배치 단계입니다. PodGroup을 확인합니다.
kubectl get podgroups.scheduling.run.ai -n kbm-g-np-example
kubectl describe podgroups.scheduling.run.ai -n kbm-g-np-example <podgroup-name>
kubectl get podgroups.scheduling.volcano.sh -n kbm-g-np-example
kubectl describe podgroups.scheduling.volcano.sh -n kbm-g-np-example <podgroup-name>
KAI를 사용하는 워크로드(TrainJob의 KAI Runtime, Dynamo, KAI 직접 설정)는 scheduling.run.ai를 확인합니다. Volcano를 사용하는 워크로드(TrainJob의 Volcano Runtime, LLMInferenceService, Volcano 직접 설정)는 scheduling.volcano.sh를 확인합니다. minMember는 필요한 Pod 수이며, describe 결과의 이벤트에 배치 공간이 부족한 이유가 표시됩니다.
kubectl get events -n kbm-g-np-example --sort-by=.lastTimestamp
kubectl describe pod -n kbm-g-np-example <pod-name>
gang 이 채워지지 않는 대표 원인:
minMember만큼의 GPU 노드가 동시에 비어 있지 않음- hard 토폴로지 Runtime에서 같은 HyperNode(IB spine) 안에 모든 Pod를 배치할 공간이 없음
- Pod 생성 자체가 실패해 gang 멤버 수가 모자람(worker 템플릿 부분 덮어쓰기, 이미지 없음, admission webhook 거부 등)
- Pod의
requests에nvidia.com/mlnxnics를 함께 요청하지 않아 IB 네트워크가 연결되지 않고ContainerCreating상태에 머묾
주의 사항
- Gang Scheduling은 Kueue 입장 이후의 배치 단계에서만 동작합니다. 우선순위와 선점은 Kueue가 WorkloadPriorityClass로 결정하며, 스케줄러는 선점하지 않습니다.
- TrainJob에는
scheduling.volcano.sh/queue-name어노테이션이나kai.scheduler/queue라벨을 지정하지 마세요. 지정하면 생성이 거부됩니다. 직접 설정하는 Job, JobSet, Deployment, Pod에는 KAI 큐 라벨kai.scheduler/queue: default-queue만 사용합니다. Volcano 큐 어노테이션은 사용하지 않습니다. - 학습 코드의
world size는numNodes와 일치해야 합니다. Gang Scheduling은 Pod 수를 보장하지만 학습 프레임워크의 rendezvous를 대신하지 않습니다.
오토스케일링
오토스케일링 개요
KEDA는 요청량이나 대기열 같은 메트릭을 읽어 워크로드의 replica 수를 자동으로 조절합니다. 자신의 Namespace에 ScaledObject를 만들고 확장 대상, 메트릭, 최소·최대 Replica 수를 지정합니다. 이 가이드는 Deployment와 DynamoGraphDeployment의 트래픽 기반 확장을 다룹니다.
| 담당 | 역할 |
|---|---|
| KEDA / HPA | 메트릭을 기준으로 필요한 Replica 수 결정 |
| Kueue / 자원 Quota | 추가 워크로드가 테넌트 자원 한도 안에서 실행될 수 있는지 통제 |
| 스케줄러 | 실행할 Pod를 노드에 배치 |
Prometheus endpoint는 http://prom-stack-kube-prometheus-prometheus.monitoring.svc:9090입니다. ScaledObject의 serverAddress에 지정합니다.
replica 수가 늘어도 GPU 자원과 quota가 부족하면 추가 Pod는 바로 실행되지 않습니다. 기존 워크로드의 LocalQueue·스케줄러·자원 요청 설정은 그대로 필요합니다.
사용 범위와 권한
ScaledObject는 Namespace 리소스이며, scaleTargetRef의 대상도 같은 Namespace에 있어야 합니다. 다른 Namespace의 Deployment나 Dynamo 컴포넌트를 대상으로 지정할 수 없습니다. 사용자 권한은 해당 Namespace의 RoleBinding 범위로 적용됩니다.
먼저 본인 계정으로 사용할 Namespace의 권한을 확인합니다. 아래 예제의 kbm-g-np-example은 본인 Namespace로 바꿉니다.
kubectl auth can-i create scaledobjects.keda.sh -n kbm-g-np-example
kubectl auth can-i create triggerauthentications.keda.sh -n kbm-g-np-example
no가 나오면 운영자에게 해당 Namespace의 권한 설정을 요청합니다. ClusterRole이나 ClusterRoleBinding을 고객이 직접 만들 필요는 없습니다.
Deployment 설정
이미 실행 중인 Deployment에 ScaledObject를 연결합니다. 아래 예제는 inference라는 Deployment의 전체 활성 요청 수를 기준으로 replica를 1~4개로 조절하는 설정입니다.
inference_active_requests는 설명용 메트릭 이름입니다.
실제로 Prometheus에 수집되는 메트릭과 라벨로 query를 바꿔야 합니다. service 라벨 존재 여부도 확인합니다. threshold 8, 최대 replica 4, 축소 대기 300초는 예시이며 모델 성능을 보장하는 권장값이 아닙니다.
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
name: inference-autoscaler
namespace: kbm-g-np-example
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: inference
pollingInterval: 30
minReplicaCount: 1
maxReplicaCount: 4
advanced:
horizontalPodAutoscalerConfig:
behavior:
scaleDown:
stabilizationWindowSeconds: 300
policies:
- type: Pods
value: 1
periodSeconds: 60
triggers:
- type: prometheus
metricType: AverageValue
metadata:
serverAddress: http://prom-stack-kube-prometheus-prometheus.monitoring.svc:9090
query: sum(inference_active_requests{namespace="kbm-g-np-example", service="inference"})
threshold: "8"
ignoreNullValues: "false"
파일을 scaledobject.yaml로 저장한 뒤 적용합니다.
kubectl apply -f scaledobject.yaml
| 필드 | 의미 |
|---|---|
| scaleTargetRef.name | 같은 namespace에 있는 확장 대상 이름 |
| minReplicaCount / maxReplicaCount | 유지할 최소·최대 replica 수. GPU 서빙 예제는 최소 1개 유지 |
| pollingInterval | KEDA의 트리거 확인 간격. 1개 이상 replica의 조절에는 HPA 자체 조회 주기도 관여 |
| query | 해당 서비스의 부하를 하나의 수치로 반환하는 PromQL |
| metricType: AverageValue / threshold | 전체 부하를 replica 당 목표값으로 나누어 확장 판단 |
| scaleDown.stabilizationWindowSeconds | 일시적인 부하 감소로 즉시 축소하지 않도록 축소 판단 안정화 |
| scaleDown.policies | 예제에서는 60초 동안 최대 1개씩 축소 |
| ignoreNullValues: false | 빈 조회 결과를 정상적인 0 부하로 처리하지 않고 오류로 확인 |
예를 들어 query가 전체 활성 요청 24를 반환하고 threshold가 8이면, 단순 목표 계산은 3 replica입니다. 실제 조절은 HPA 허용 오차, 안정화 정책, 최소·최대값 및 Pod 상태에 따라 달라집니다. cooldownPeriod는 0개로 축소할 때 적용되는 값이므로, 최소 1개를 유지하는 이 예제의 축소 대기에는 HPA behavior를 사용합니다.
Dynamo 설정
Dynamo는 생성된 하위 Deployment를 직접 확장하지 않고 DynamoGraphDeploymentScalingAdapter를 대상으로 사용합니다. 운영 Dynamo 1.4.2의 v1beta1 CRD에서는 자동확장할 컴포넌트에 scalingAdapter: {}를 넣으면 DGDSA가 생성되고 Replica 관리가 DGDSA로 넘어갑니다.
아래는 기존 DGD의 해당 컴포넌트에 추가할 필드만 보여 주는 부분 예시입니다. 이 조각으로 전체 components 목록을 덮어쓰지 말고 기존 image, resources, podTemplate 등을 유지합니다.
spec:
components:
- name: VllmWorker
scalingAdapter: {}
생성된 DGDSA의 실제 이름을 확인한 뒤, 앞의 ScaledObject에서 scaleTargetRef를 다음과 같이 바꿉니다. DGDSA 조회 권한이 없다면 운영자에게 대상 이름과 생성 상태를 확인받습니다.
scaleTargetRef:
apiVersion: nvidia.com/v1beta1
kind: DynamoGraphDeploymentScalingAdapter
name: <생성된-DGDSA-이름>
전체 예시 (Prefill, Decode 분리 예제)
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
name: glm-5-3-disagg-prefill
namespace: kbm-g-np-example
spec:
scaleTargetRef:
apiVersion: nvidia.com/v1beta1
kind: DynamoGraphDeploymentScalingAdapter
name: glm-5-3-disagg-vllmprefillworker
minReplicaCount: 1
maxReplicaCount: 3
advanced:
horizontalPodAutoscalerConfig:
behavior:
scaleUp:
stabilizationWindowSeconds: 30
policies:
- type: Pods
value: 1
periodSeconds: 60
scaleDown:
stabilizationWindowSeconds: 600
policies:
- type: Pods
value: 1
periodSeconds: 300
triggers:
- type: prometheus
metricType: AverageValue
metadata:
serverAddress: http://prom-stack-kube-prometheus-prometheus.monitoring.svc:9090
query: sum(vllm:num_requests_waiting_by_reason{dynamo_namespace="kbm-g-np-example-glm-5-3-disagg", dynamo_component_type="prefill", reason="capacity"})
threshold: "4"
ignoreNullValues: "false"
---
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
name: glm-5-3-disagg-decode
namespace: kbm-g-np-example
spec:
scaleTargetRef:
apiVersion: nvidia.com/v1beta1
kind: DynamoGraphDeploymentScalingAdapter
name: glm-5-3-disagg-vllmdecodeworker
minReplicaCount: 1
maxReplicaCount: 3
advanced:
horizontalPodAutoscalerConfig:
behavior:
scaleUp:
stabilizationWindowSeconds: 30
policies:
- type: Pods
value: 1
periodSeconds: 60
scaleDown:
stabilizationWindowSeconds: 600
policies:
- type: Pods
value: 1
periodSeconds: 300
triggers:
- type: prometheus
metricType: AverageValue
metadata:
serverAddress: http://prom-stack-kube-prometheus-prometheus.monitoring.svc:9090
query: sum(vllm:num_requests_waiting_by_reason{dynamo_namespace="kbm-g-np-example-glm-5-3-disagg", dynamo_component_type="decode", reason="capacity"})
threshold: "8"
ignoreNullValues: "false"
- ScaledObject는 DGDSA와 같은 namespace에 생성합니다. 앞의 Deployment 예제에 쓴 query도 Dynamo에서 실제 수집되는 해당 모델·컴포넌트의 메트릭으로 바꿉니다.
- Dynamo worker는 minReplicaCount를 1 이상으로 두고 시작합니다. 이 가이드는 Dynamo의 0개 축소를 다루지 않습니다.
- DGDSA를 사용하는 컴포넌트의 replicas를 수동 설정이나 다른 autoscaler로 동시에 제어하지 않습니다. Planner를 이미 쓰고 있다면 같은 대상에 KEDA를 중복 연결하지 않습니다.
- 멀티노드 컴포넌트는 replica 하나가 여러 Pod와 GPU를 사용하는 단위입니다. maxReplicaCount는 replica 당 전체 GPU 요구량과 테넌트 quota를 함께 계산해 정합니다.
상태 확인
kubectl get scaledobjects.keda.sh -n kbm-g-np-example
kubectl describe scaledobject inference-autoscaler -n kbm-g-np-example
kubectl get hpa -n kbm-g-np-example
kubectl describe hpa keda-hpa-inference-autoscaler -n kbm-g-np-example
kubectl get deployment inference -n kbm-g-np-example
kubectl get events -n kbm-g-np-example --sort-by=.lastTimestamp
| 상태 | 확인할 내용 |
|---|---|
| ScaledObject Ready=False | 대상 이름·API 버전, Prometheus 연결, 쿼리 오류, 인증 설정과 이벤트 |
| Active=False | 트리거 비활성일 수 있음. 그 자체로 오류는 아니며 Ready와 이벤트를 함께 확인 |
| HPA TARGETS에 unknown 표시 | 메트릭 조회 오류와 HPA 이벤트 확인 |
| 원하는 replica는 증가했지만 Ready Pod가 늘지 않음 | quota, Kueue Workload, Pod 이벤트, GPU 가용량 및 모델 로딩 상태 확인 |
| Forbidden | 본인 namespace의 ScaledObject 권한 확인. 컨트롤러 이벤트의 Forbidden은 운영자가 KEDA 서비스 계정 권한 확인 |
일시 중지와 해제
현재 replica 수를 유지하면서 KEDA 자동확장을 잠시 멈추려면 paused 어노테이션을 사용합니다.
kubectl annotate scaledobject inference-autoscaler -n kbm-g-np-example autoscaling.keda.sh/paused=true --overwrite
다시 자동확장을 시작하려면 어노테이션을 제거합니다.
kubectl annotate scaledobject inference-autoscaler -n kbm-g-np-example autoscaling.keda.sh/paused-
자동확장을 제거하려면 ScaledObject를 삭제합니다. 기본 설정에서는 원래 replica 수로 자동 복원되지 않으므로 삭제 후 원하는 고정 replica 수를 별도로 확인합니다.
kubectl delete scaledobject inference-autoscaler -n kbm-g-np-example
참고 메트릭
| 구분 | 링크 |
|---|---|
| vllm | vLLM Grafana Dashboard Metrics |
| dynamo | NVIDIA Dynamo Metric Labels |
| sglang | SGLang Production Metrics |
| envoy | Envoy Configuration Stats |
메트릭 설정
Dynamo를 사용하지 않고 vLLM 또는 SGLang을 별도 Pod/Deployment로 실행할 때는, 실제 추론 서버 Pod의 label과 컨테이너 포트 이름을 아래와 같이 설정합니다. 플랫폼 Prometheus가 Pod IP의 /metrics를 직접 수집하므로, 메트릭 수집만을 위한 Service/Ingress/ServiceMonitor/PodMonitor를 고객이 별도로 만들 필요는 없습니다.
vLLM 설정 예시
아래는 기존 Deployment에 합칠 메트릭 관련 일부 필드입니다.
다음처럼 서버가 8000 포트에서 실행 중인 경우:
vllm serve <모델 ID 또는 경로> --host 0.0.0.0 --port 8000
Deployment의 해당 컨테이너에 다음을 반영합니다.
spec:
template:
metadata:
labels:
natl.kakaocloud.com/endpoint.serving-type: vllm
spec:
containers:
- name: vllm
ports:
- name: modelserver
containerPort: 8000
protocol: TCP
기존 포트가 이미 선언되어 있으면 그 포트 항목의 이름을 modelserver로 맞춥니다. 기존 Service의 targetPort나 probe가 이전 포트 이름을 참조한다면 함께 맞춰야 합니다.
SGLang 설정 예시
SGLang은 기존 서버 실행 인자에 --enable-metrics를 추가합니다. 예를 들어 30000 포트를 사용할 때의 실행 명령은 다음과 같습니다.
python3 -m sglang.launch_server --model-path <모델 ID 또는 경로> --host 0.0.0.0 --port 30000 --enable-metrics
기존 Deployment의 Pod 템플릿에는 다음 필드를 합칩니다. 컨테이너 이름은 실제 이름에 맞춥니다.
spec:
template:
metadata:
labels:
natl.kakaocloud.com/endpoint.serving-type: sglang
spec:
containers:
- name: sglang
ports:
- name: modelserver
containerPort: 30000
protocol: TCP
modelserver는 고정된 포트 이름이고, 8000/30000은 예시 포트 번호입니다. 다른 번호를 쓰면 containerPort를 실제 /metrics 응답 포트에 맞춥니다. containerPort 선언 자체가 서버의 리스닝 포트를 변경하거나 메트릭을 활성화하지는 않습니다.
서버는 Pod IP에서 접근할 수 있도록 리스닝해야 하며, 127.0.0.1에만 바인딩하면 Prometheus가 수집할 수 없습니다.