NVIDIA device plugin for Kubernetes

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: nvidia-device-plugin-daemonset
  namespace: kube-system
spec:
  selector:
    matchLabels:
      name: nvidia-device-plugin-ds
  updateStrategy:
    type: RollingUpdate
  template:
    metadata:
      labels:
        name: nvidia-device-plugin-ds
    spec:
      runtimeClassName: nvidia          # <-- k3s 용 로컬 수정 (아래 참고)
      tolerations:
      - key: nvidia.com/gpu
        operator: Exists
        effect: NoSchedule
      priorityClassName: "system-node-critical"
      containers:
      - image: nvcr.io/nvidia/k8s-device-plugin:v0.17.1
        name: nvidia-device-plugin-ctr
        env:
          - name: FAIL_ON_INIT_ERROR
            value: "false"
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop: ["ALL"]
        volumeMounts:
        - name: device-plugin
          mountPath: /var/lib/kubelet/device-plugins
      volumes:
      - name: device-plugin
        hostPath:
          path: /var/lib/kubelet/device-plugins

apiVersion: v1
kind: ConfigMap
metadata:
  name: nvidia-device-plugin-config
  namespace: kube-system
data:
  config.yaml: |
    version: v1
    sharing:
      timeSlicing:
        resources:
          - name: nvidia.com/gpu
            replicas: 4        # 1장을 4개처럼 광고

        env:
          - name: FAIL_ON_INIT_ERROR
            value: "false"
          - name: CONFIG_FILE
            value: /config/config.yaml
        volumeMounts:
        - name: device-plugin
          mountPath: /var/lib/kubelet/device-plugins
        - name: plugin-config
          mountPath: /config
      volumes:
      - name: device-plugin
        hostPath:
          path: /var/lib/kubelet/device-plugins
      - name: plugin-config
        configMap:
          name: nvidia-device-plugin-config

apiVersion: v1
kind: ResourceQuota
metadata:
  name: gpu-quota
  namespace: tenant-kia
spec:
  hard:
    requests.nvidia.com/gpu: "1"

# NVIDIA device plugin — 노드가 GPU 를 **스케줄 가능한 자원**으로 광고하게 한다.
# (plan 17 S9)
#
# 왜 필요한가: `RuntimeClass nvidia` 만으로도 파드에 GPU 를 밀어 넣을 수는 있지만,
# 그러면 클러스터가 GPU 점유를 모른다. GPU 가 하나뿐인 노드에서 서빙 엔드포인트를 둘
# 만들면 둘 다 같은 8 GB 를 잡고 서로 OOM 낸다. 이 플러그인이 `nvidia.com/gpu` 를
# 광고하면 두 번째 엔드포인트는 런타임에 죽는 대신 Pending 으로 대기한다 — 같은 실패라도
# 스케줄러가 아는 실패가 낫다. 그 상한을 올리는 것이 아래 시분할 설정이다.
#
# 원본: https://github.com/NVIDIA/k8s-device-plugin (v0.19.3, Apache-2.0)
# 로컬 수정: `runtimeClassName: nvidia` 한 줄. k3s 의 기본 런타임은 nvidia 가 아니라서
# 이게 없으면 플러그인 컨테이너가 NVML 을 못 열고 GPU 를 0개로 보고한다.
#
# 버전 하한: v0.18.2 ("Ignore errors getting device memory using NVML"). 통합 메모리
# GPU 는 `nvmlDeviceGetMemoryInfo` 에 `Not Supported` 를 돌려주는데, 그 이전 버전은
# 이것을 치명적 오류로 보고 디바이스 열거 자체를 포기한다 — GPU 를 정상 인식하고도
# `error building device map ... error getting device memory: Not Supported` 로 죽는다.
#
# 시분할(time-slicing): DGX Spark 는 GPU 가 **하나**다. 기본 설정이면 노드는
# `nvidia.com/gpu: 1` 만 광고하므로 두 번째 엔드포인트부터 영원히 Pending 이다
# (`0/1 nodes are available: 1 Insufficient nvidia.com/gpu`). 아래 ConfigMap 이
# 그 하나를 `replicas` 개의 논리 GPU 로 광고해 여러 인스턴스가 같은 GPU 를 나눠 쓰게
# 한다. GB10 은 MIG 를 지원하지 않으므로 하드웨어 분할은 선택지가 아니다.
#
# 시분할이 나눠 주는 것은 **실행 시간뿐이다.** 메모리는 격리되지 않는다 — 128 GB 통합
# 메모리를 N 개 파드가 그냥 같이 쓴다. 즉 `replicas` 는 "동시에 띄울 인스턴스 수"이지
# "안전하게 띄울 수 있는 수"가 아니다. 인스턴스 하나가 메모리를 다 먹으면 나머지는
# 여전히 OOM 이다. 다만 실패 지점이 스케줄러(Pending)에서 런타임으로 옮겨갈 뿐이다.
#
# `replicas` 조정: 동시에 돌릴 인스턴스 수보다 넉넉하게 잡는다. 광고만 하는 숫자라
# 남아도는 슬롯에 비용은 없다. 바꾼 뒤에는 **반드시 롤아웃**해야 반영된다:
#     kubectl -n kube-system rollout restart ds/nvidia-device-plugin-daemonset
#
# `renameByDefault: false` 를 유지하는 이유: true 면 자원 이름이
# `nvidia.com/gpu.shared` 로 바뀌어 앱의 `serving_gpu_resource`(config.py) 와
# 학습 러너의 요청까지 전부 따라 바꿔야 한다.
#
# `failRequestsGreaterThanOne: true` 를 켜는 이유: 시분할 슬롯 2개는 GPU 2장이
# 아니다. 이게 없으면 `gpu: 2` 요청이 스케줄에 성공한 뒤 실제로는 GPU 하나를 자기끼리
# 시분할하는, 조용히 틀린 상태가 된다. 켜 두면 admission 단계에서 즉시 거부된다.
#
# 적용 (sudo 불필요 — kubeconfig 만 있으면 된다):
#     kubectl apply -f scripts/serving/nvidia-device-plugin.yml
#
# 확인 (노드가 여럿이면 `items[0]` 은 GPU 노드가 아닐 수 있다 — 전부 본다):
#     kubectl get nodes -o custom-columns='NAME:.metadata.name,ALLOC:.status.allocatable.nvidia\.com/gpu'
apiVersion: v1
kind: ConfigMap
metadata:
  name: nvidia-device-plugin-config
  namespace: kube-system
data:
  # 파일 하나만 두고 DaemonSet 이 `CONFIG_FILE` 로 직접 가리킨다. 노드마다 다른 설정을
  # 쓰려면(`nvidia.com/device-plugin.config` 라벨) config-manager 사이드카가 필요한데,
  # 단일 노드에는 과하다.
  config.yaml: |-
    version: v1
    flags:
      migStrategy: none
    sharing:
      timeSlicing:
        renameByDefault: false
        failRequestsGreaterThanOne: true
        resources:
        - name: nvidia.com/gpu
          replicas: 8
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: nvidia-device-plugin-daemonset
  namespace: kube-system
spec:
  selector:
    matchLabels:
      name: nvidia-device-plugin-ds
  updateStrategy:
    type: RollingUpdate
  template:
    metadata:
      labels:
        name: nvidia-device-plugin-ds
    spec:
      runtimeClassName: nvidia
      tolerations:
      - key: nvidia.com/gpu
        operator: Exists
        effect: NoSchedule
      # Mark this pod as a critical add-on; when enabled, the critical add-on
      # scheduler reserves resources for critical add-on pods so that they can
      # be rescheduled after a failure.
      # See https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/
      priorityClassName: "system-node-critical"
      containers:
      - image: nvcr.io/nvidia/k8s-device-plugin:v0.19.3
        name: nvidia-device-plugin-ctr
        env:
          - name: FAIL_ON_INIT_ERROR
            value: "false"
          # 시분할 설정을 읽는다. 이 줄이 없으면 ConfigMap 은 마운트만 되고 무시된다.
          - name: CONFIG_FILE
            value: /etc/nvidia-device-plugin/config.yaml
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop: ["ALL"]
        volumeMounts:
        - name: device-plugin
          mountPath: /var/lib/kubelet/device-plugins
        - name: plugin-config
          mountPath: /etc/nvidia-device-plugin
          readOnly: true
      volumes:
      - name: device-plugin
        hostPath:
          path: /var/lib/kubelet/device-plugins
      - name: plugin-config
        configMap:
          name: nvidia-device-plugin-config