Kubernetes RuntimeClass와 GPU 스케줄링 운영 가이드

Pod spec (runtimeClassName + resources)
    → RuntimeClass (handler 매핑)
        → 컨테이너 런타임 (containerd + nvidia handler)
            → NVIDIA Device Plugin (GPU 리소스 등록)
                → GPU 드라이버 (호스트 커널 모듈)

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: nvidia
# handler는 containerd 설정의 runtime handler 이름과 일치해야 한다
handler: nvidia
scheduling:
  # 이 RuntimeClass를 사용하는 Pod를 특정 노드에만 스케줄링
  nodeSelector:
    accelerator: nvidia-gpu
  tolerations:
    - key: nvidia.com/gpu
      operator: Exists
      effect: NoSchedule
overhead:
  # 런타임 오버헤드 (gVisor 등 샌드박스 런타임 사용 시 설정)
  podFixed:
    cpu: '100m'
    memory: '128Mi'

# /etc/containerd/config.toml (GPU 노드)
version = 2

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]
  runtime_type = "io.containerd.runc.v2"

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options]
  BinaryName = "/usr/bin/nvidia-container-runtime"

sudo systemctl restart containerd
# 핸들러 등록 확인
sudo crictl info | jq '.config.containerd.runtimes | keys'
# 출력: ["nvidia", "runc"]

apiVersion: v1
kind: Pod
metadata:
  name: gpu-inference
spec:
  runtimeClassName: nvidia # RuntimeClass 지정
  containers:
    - name: model-server
      image: nvcr.io/nvidia/tritonserver:24.08-py3
      resources:
        limits:
          nvidia.com/gpu: 1
      ports:
        - containerPort: 8000
          name: http
        - containerPort: 8001
          name: grpc

# NVIDIA Device Plugin 배포 (v0.17.0 기준)
kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.17.0/deployments/static/nvidia-device-plugin.yml

# 노드별 GPU 리소스 확인
kubectl get nodes -o json | jq '.items[] |
  select(.status.capacity["nvidia.com/gpu"] != null) |
  {name: .metadata.name,
   gpu_capacity: .status.capacity["nvidia.com/gpu"],
   gpu_allocatable: .status.allocatable["nvidia.com/gpu"]}'

{
  "name": "gpu-node-01",
  "gpu_capacity": "4",
  "gpu_allocatable": "4"
}
{
  "name": "gpu-node-02",
  "gpu_capacity": "8",
  "gpu_allocatable": "7"
}

# Helm으로 GPU Operator 설치
helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
helm repo update

helm install gpu-operator nvidia/gpu-operator \
  --namespace gpu-operator \
  --create-namespace \
  --set driver.enabled=true \
  --set toolkit.enabled=true \
  --set devicePlugin.enabled=true \
  --set dcgmExporter.enabled=true \
  --set migManager.enabled=false  # MIG 미사용 시

# GPU 노드에 라벨 추가
kubectl label node gpu-node-01 \
  accelerator=nvidia-gpu \
  gpu.nvidia.com/model=A100 \
  gpu.nvidia.com/memory=80Gi

# GPU 노드에 Taint 추가 (GPU 워크로드만 스케줄링)
kubectl taint node gpu-node-01 \
  nvidia.com/gpu=present:NoSchedule

apiVersion: apps/v1
kind: Deployment
metadata:
  name: llm-inference
  namespace: ml-serving
spec:
  replicas: 2
  selector:
    matchLabels:
      app: llm-inference
  template:
    metadata:
      labels:
        app: llm-inference
    spec:
      runtimeClassName: nvidia
      nodeSelector:
        accelerator: nvidia-gpu
        gpu.nvidia.com/model: A100
      tolerations:
        - key: nvidia.com/gpu
          operator: Equal
          value: present
          effect: NoSchedule
      containers:
        - name: vllm
          image: vllm/vllm-openai:v0.6.4
          args:
            - '--model'
            - 'meta-llama/Llama-3.1-8B-Instruct'
            - '--tensor-parallel-size'
            - '1'
            - '--gpu-memory-utilization'
            - '0.9'
          resources:
            requests:
              cpu: '4'
              memory: '32Gi'
              nvidia.com/gpu: 1
            limits:
              cpu: '8'
              memory: '64Gi'
              nvidia.com/gpu: 1
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 120
            periodSeconds: 10

# GPU에서 MIG 활성화 (노드에 SSH 접속 후)
sudo nvidia-smi -i 0 -mig 1

# MIG 프로파일 생성 (A100 80GB 기준)
# 3g.40gb 인스턴스 2개 생성
sudo nvidia-smi mig -i 0 -cgi 9,9 -C

# 생성된 MIG 인스턴스 확인
nvidia-smi -L

GPU 0: NVIDIA A100-SXM4-80GB (UUID: GPU-xxxxx)
  MIG 3g.40gb Device 0: (UUID: MIG-xxxxx)
  MIG 3g.40gb Device 1: (UUID: MIG-xxxxx)

apiVersion: v1
kind: ConfigMap
metadata:
  name: mig-parted-config
  namespace: gpu-operator
data:
  config.yaml: |
    version: v1
    mig-configs:
      # 프로파일 A: 추론용 (작은 인스턴스 여러 개)
      inference-optimized:
        - devices: [0]
          mig-enabled: true
          mig-devices:
            "1g.10gb": 7
      # 프로파일 B: 학습용 (큰 인스턴스 소수)
      training-optimized:
        - devices: [0]
          mig-enabled: true
          mig-devices:
            "3g.40gb": 2
      # 프로파일 C: MIG 비활성화
      full-gpu:
        - devices: [0]
          mig-enabled: false

# 추론 서버용 MIG 프로파일 적용
kubectl label node gpu-node-01 nvidia.com/mig.config=inference-optimized --overwrite

# ServiceMonitor (Prometheus Operator 사용 시)
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: dcgm-exporter
  namespace: monitoring
  labels:
    release: prometheus
spec:
  selector:
    matchLabels:
      app: nvidia-dcgm-exporter
  endpoints:
    - port: metrics
      interval: 15s
      path: /metrics

# PrometheusRule - GPU 알림
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: gpu-alerts
  namespace: monitoring
spec:
  groups:
    - name: gpu.rules
      rules:
        # GPU 사용률 10% 미만이 30분 지속 → 리소스 낭비
        - alert: GPUUnderutilized
          expr: |
            avg_over_time(DCGM_FI_DEV_GPU_UTIL[30m]) < 10
            and on(pod) kube_pod_status_phase{phase="Running"} == 1
          for: 30m
          labels:
            severity: warning
          annotations:
            summary: 'GPU 사용률 10% 미만 지속 ({{ $labels.gpu }})'
            description: '노드 {{ $labels.node }}의 GPU {{ $labels.gpu }}가 30분간 사용률 10% 미만. MIG 분할 또는 워크로드 통합 검토.'

        # GPU 메모리 95% 이상 → OOM 위험
        - alert: GPUMemoryPressure
          expr: |
            DCGM_FI_DEV_FB_USED / DCGM_FI_DEV_FB_FREE > 19
          for: 5m
          labels:
            severity: critical
          annotations:
            summary: 'GPU 메모리 95% 이상 ({{ $labels.gpu }})'
            description: '노드 {{ $labels.node }}의 GPU {{ $labels.gpu }} 메모리 사용률 95% 초과. 배치 크기 축소 또는 모델 양자화 필요.'

        # GPU 온도 85도 이상 → 서멀 스로틀링 위험
        - alert: GPUTemperatureHigh
          expr: DCGM_FI_DEV_GPU_TEMP > 85
          for: 10m
          labels:
            severity: warning
          annotations:
            summary: 'GPU 온도 85도 초과 ({{ $labels.gpu }})'

# GPU 사용률 (전체 클러스터)
avg(DCGM_FI_DEV_GPU_UTIL) by (node, gpu)

# GPU 메모리 사용률
DCGM_FI_DEV_FB_USED / (DCGM_FI_DEV_FB_USED + DCGM_FI_DEV_FB_FREE) * 100

# GPU당 할당된 Pod 수
count(kube_pod_container_resource_limits{resource="nvidia_com_gpu"}) by (node)

# Pending GPU Pod 수 (스케줄링 대기)
count(kube_pod_status_phase{phase="Pending"})
  * on(pod) group_left()
  kube_pod_container_resource_requests{resource="nvidia_com_gpu"}

$ kubectl describe pod gpu-job-xyz
Events:
  Warning  FailedScheduling  0/10 nodes are available:
    3 node(s) had untolerated taint {nvidia.com/gpu: present},
    7 node(s) didn't match Pod's node affinity/selector.

# 1. 노드 라벨 확인
kubectl get nodes --show-labels | grep accelerator

# 2. 노드 Taint 확인
kubectl describe node gpu-node-01 | grep -A5 Taints

# 3. Pod spec에 toleration과 nodeSelector 추가 확인

$ kubectl describe pod gpu-job-xyz
Events:
  Warning  FailedValidation  RuntimeClass "nvidia" not found

# RuntimeClass 존재 여부 확인
kubectl get runtimeclass

# 없으면 생성
kubectl apply -f - <<EOF
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: nvidia
handler: nvidia
EOF

$ kubectl describe node gpu-node-01 | grep nvidia
# 아무것도 출력되지 않음

# 1. Device Plugin Pod 상태 확인
kubectl -n kube-system get pods | grep nvidia-device-plugin
# STATUS가 Running이 아니면 로그 확인

# 2. Device Plugin 로그 확인
kubectl -n kube-system logs nvidia-device-plugin-xxxxx
# 예상 에러: "Failed to initialize NVML: Driver Not Loaded"
# → 호스트에 NVIDIA 드라이버가 설치되지 않음

# 3. 노드에서 직접 확인 (SSH)
nvidia-smi
# Command not found → 드라이버 미설치
# NVIDIA-SMI has failed → 드라이버 버전과 커널 불일치

# 4. 드라이버 설치 확인
dpkg -l | grep nvidia-driver
# 또는
rpm -qa | grep nvidia-driver

RuntimeError: CUDA out of memory. Tried to allocate 2.00 GiB
(GPU 0; 79.35 GiB total capacity; 77.31 GiB already allocated)

# 옵션 1: 더 큰 GPU 또는 더 많은 GPU 사용
resources:
  limits:
    nvidia.com/gpu: 2  # 1 → 2

# 옵션 2: 모델 최적화
# vLLM 사용 시 --gpu-memory-utilization 조절
args: ["--gpu-memory-utilization", "0.85"]  # 0.9 → 0.85

# 옵션 3: 배치 크기 축소
# 추론 서버의 max-batch-size 설정 낮추기

# 옵션 4: 모델 양자화 (INT8/INT4)
# 모델 파일 자체를 양자화된 버전으로 교체

# 업그레이드 전 호환성 매트릭스 확인
# 1. Kubernetes 버전
kubectl version --short

# 2. NVIDIA Driver 버전
nvidia-smi --query-gpu=driver_version --format=csv,noheader

# 3. Device Plugin 버전
kubectl -n kube-system get ds nvidia-device-plugin-daemonset \
  -o jsonpath='{.spec.template.spec.containers[0].image}'

# 4. Container Toolkit 버전
nvidia-container-cli --version

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: gpu-resource-governance
spec:
  validationFailureAction: Enforce
  rules:
    # 규칙 1: GPU 요청 시 반드시 limits도 설정
    - name: require-gpu-limits
      match:
        any:
          - resources:
              kinds: ['Pod']
      preconditions:
        all:
          - key: '{{ request.object.spec.containers[].resources.requests."nvidia.com/gpu" || '''' }}'
            operator: NotEquals
            value: ''
      validate:
        message: 'GPU를 requests에 넣었으면 limits에도 동일하게 설정하세요.'
        pattern:
          spec:
            containers:
              - resources:
                  limits:
                    nvidia.com/gpu: '?*'

    # 규칙 2: GPU Pod에 privileged 금지
    - name: deny-privileged-gpu-pods
      match:
        any:
          - resources:
              kinds: ['Pod']
      preconditions:
        all:
          - key: '{{ request.object.spec.containers[].resources.limits."nvidia.com/gpu" || '''' }}'
            operator: NotEquals
            value: ''
      validate:
        message: 'GPU Pod에서 privileged 모드는 보안상 금지됩니다.'
        pattern:
          spec:
            containers:
              - =(securityContext):
                  =(privileged): false

    # 규칙 3: GPU Pod에 runtimeClassName 필수
    - name: require-nvidia-runtimeclass
      match:
        any:
          - resources:
              kinds: ['Pod']
      preconditions:
        all:
          - key: '{{ request.object.spec.containers[].resources.limits."nvidia.com/gpu" || '''' }}'
            operator: NotEquals
            value: ''
      validate:
        message: 'GPU Pod는 반드시 runtimeClassName: nvidia를 지정해야 합니다.'
        pattern:
          spec:
            runtimeClassName: nvidia