🧩

ASUS GX10(DGX Spark)을 GPU 노드로 조인하기 — containerd CRI, 노드 IP, Cilium, device plugin

최민석·2026-08-30

집에서 굴리는 온프레미스 쿠버네티스 클러스터에 GPU 노드를 한 대 붙였습니다. ASUS Ascent GX10, NVIDIA DGX Spark 계열의 워크스테이션입니다.

기존 클러스터는 control-plane 3대와 worker 3대로 돌아가고 있었고, 노드를 늘리는 일은 그동안 몇 번 해 봤기 때문에 kubeadm join 한 줄이면 끝날 거라고 생각했습니다. 실제로는 조인이 붙고 나서도 노드가 정상 상태가 되기까지 네 군데에서 막혔습니다.

원인은 전부 이 노드가 기존 여섯 대와 다른 지점에서 나왔습니다. 유일한 arm64이고, OS 이미지가 벤더가 만든 것이고, GPU와 CPU가 메모리를 공유하고, 네트워크 인터페이스 이름이 다릅니다. 하나하나는 사소한데, 클러스터 쪽 설정이 나머지 노드를 기준으로 맞춰져 있다 보니 전부 걸림돌이 됐습니다.

항목 기존 6대 gx10
아키텍처 amd64 arm64
OS Ubuntu 22.04 Ubuntu 24.04 (벤더 이미지)
커널 5.15 intel-iotg 6.17 nvidia
네트워크 인터페이스 ens18 enP7s7
메모리 일반 121Gi CPU·GPU 통합

클러스터는 v1.30.14, CNI는 Cilium(native routing), 런타임은 containerd입니다.

본론에 들어가기 전에 kubeadm join이 하는 일을 짚어 두면 뒤의 문제들이 어디서 생기는지 따라가기 쉽습니다. 새 노드에서 이 명령을 실행하면 kubelet이 control-plane의 API 서버에 접속해 임시 토큰으로 자신을 인증하고, 노드용 클라이언트 인증서를 발급받은 뒤 Node 오브젝트를 등록합니다. 그 다음부터는 kubelet이 자기 노드의 컨테이너 런타임(containerd)에 파드를 만들어 달라고 요청하고, CNI(Cilium)가 파드에 네트워크를 붙여 줍니다. 이번에 걸린 네 가지는 순서대로 컨테이너 런타임(2절), 노드가 자신을 알리는 IP(3절), CNI(4절), 그리고 GPU를 쿠버네티스 리소스로 노출하는 device plugin(5절)에서 나왔습니다.


1. 조인 전에 정한 것

이 노드는 AI 워크로드만 돌릴 생각이었습니다. 일반 파드가 흘러들어오면 GPU 메모리를 놓고 경쟁할 이유가 없으니, 등록 시점부터 taint를 걸어 두기로 했습니다.

taint는 조인이 끝난 뒤 kubectl taint node gx10 ...로 붙여도 됩니다. 다만 그 방식에는 짧은 틈이 있습니다. 노드가 Ready가 된 순간부터 taint를 붙이기 전까지, 스케줄러가 이 노드를 일반 노드로 보고 대기 중이던 파드를 배치할 수 있습니다. kubelet의 --register-with-taints 인자를 쓰면 Node 오브젝트가 만들어지는 시점에 taint가 함께 들어가므로 이 틈이 없습니다. 라벨도 같은 이유로 --node-labels로 등록 시점에 붙였습니다. 뒤에서 GPU 파드와 device plugin이 nodeSelector로 이 라벨을 찾습니다.

kubeadm으로 설치한 kubelet은 systemd 서비스로 돌고, 시작할 때 /etc/default/kubelet 파일의 KUBELET_EXTRA_ARGS 변수를 읽어 추가 인자로 붙입니다(/usr/lib/systemd/system/kubelet.service.d/10-kubeadm.conf가 이 파일을 EnvironmentFile로 참조합니다). 그래서 kubelet 인자를 바꿀 때는 이 파일을 고치고 systemctl restart kubelet을 합니다.

# /etc/default/kubelet
KUBELET_EXTRA_ARGS=--register-with-taints=dedicated=ai-gpu:NoSchedule \
  --node-labels=node-type=ai-gpu,gpu=nvidia-gb10 \
  --node-ip=10.0.0.33

--node-ip는 나중에 3절에서 추가한 것이고, 처음에는 앞의 두 개만 있었습니다.

조인 명령은 control-plane 노드에서 발급했습니다. 제가 kubectl을 쓰는 관리 호스트에는 kubeadm이 없어서, control-plane VM 한 대에 SSH로 들어가 토큰을 만들었습니다.

# control-plane01
$ sudo kubeadm token create --print-join-command
kubeadm join 10.0.0.99:7443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

--print-join-command가 bootstrap token과 CA 인증서 해시를 한 줄로 뽑아 주기 때문에, 이 출력을 gx10에서 그대로 실행하면 됩니다. 토큰은 기본 24시간 뒤에 만료되므로 발급하고 바로 쓰는 편이 낫습니다.

두 값의 역할은 이렇습니다. --token은 새 노드가 API 서버에 "나를 클러스터에 넣어 달라"고 요청할 때 쓰는 임시 비밀번호입니다. 반대로 --discovery-token-ca-cert-hash는 새 노드가 접속한 상대가 진짜 우리 클러스터의 API 서버인지 확인하는 용도로, 클러스터 CA 인증서 공개키의 SHA-256 해시입니다. 앞은 서버가 노드를 믿기 위한 값, 뒤는 노드가 서버를 믿기 위한 값입니다. 10.0.0.99:7443은 control-plane 세 대 앞에 둔 API 서버 VIP입니다.


2. containerd에 CRI 플러그인이 꺼져 있었다

조인 명령을 실행하기 전에 containerd부터 확인했습니다. 이 장비(ASUS GX10)는 공장 이미지에 Docker가 이미 들어 있었고, 딸려 온 containerd를 그대로 쓸 생각이었습니다.

$ dpkg-query -W containerd.io docker-ce
containerd.io   2.2.1-1~ubuntu.24.04~noble
docker-ce       5:28.3.3-1~ubuntu.24.04~noble

Ubuntu 저장소의 containerd나 docker.io 패키지가 아니라 Docker 공식 저장소의 containerd.io 패키지입니다. dpkg 로그를 보면 이 둘이 1700개 넘는 패키지와 함께 한 번에 설치되어 있습니다. grub, shim-signed, firmware, 폰트가 같은 배치에 들어 있는 걸 보면 개별 설치가 아니라 OS 이미지를 굽는 시점입니다.

2025-11-13 10:15:14 install containerd.io:arm64 <none> 1.7.26-1
2025-11-13 10:15:16 install docker-ce:arm64 <none> 5:28.3.3-1~ubuntu.24.04~noble

문제는 이 패키지가 배치하는 containerd 설정 파일 /etc/containerd/config.toml입니다. dpkg -L containerd.io로 보면 이 파일이 패키지에 포함된 것을 확인할 수 있고, 내용은 Docker Inc. 저작권 헤더 아래에 CRI 플러그인을 끄는 한 줄이 들어 있습니다.

$ dpkg -L containerd.io | grep config.toml
/etc/containerd/config.toml

$ grep -v '^#' /etc/containerd/config.toml
disabled_plugins = ["cri"]

CRI(Container Runtime Interface)는 kubelet이 컨테이너 런타임에게 "이 파드를 만들어라, 이 컨테이너를 멈춰라"를 시키는 gRPC 규격입니다. kubelet은 컨테이너를 직접 만들지 않고, /run/containerd/containerd.sock 유닉스 소켓을 통해 이 규격으로 containerd에 요청합니다. containerd 쪽에서 그 요청을 받아 주는 부품이 cri 플러그인이고, 위 설정은 그 플러그인을 통째로 꺼 놓은 것입니다.

Docker는 containerd를 쓰긴 하지만 CRI를 거치지 않고 자기 전용 API로 직접 이야기합니다. 그래서 Docker 입장에서는 CRI 플러그인이 없어도 아무 문제가 없고, 패키지 기본값으로는 합리적입니다. 그런데 kubelet은 이 CRI 소켓만 보기 때문에, 이 상태로 kubeadm join을 실행하면 preflight 단계에서 unknown service runtime.v1.RuntimeService 류의 에러가 나면서 멈춥니다. 벤더가 Docker를 미리 깔아 둔 이미지에서 쿠버네티스를 쓰려고 할 때 첫 번째로 만나는 지점이라고 봅니다.

설정을 손으로 고치는 대신 기본값으로 새로 만들었습니다. containerd config default가 만드는 설정에는 disabled_plugins가 비어 있어 CRI가 켜집니다.

다시 만든 설정에서 한 가지는 바로 고쳐야 합니다. SystemdCgroup입니다.

cgroup은 리눅스 커널이 프로세스 묶음별로 CPU·메모리 사용량을 제한하는 기능이고, 파드의 resources.limits가 최종적으로 여기에 반영됩니다. cgroup을 만들고 관리하는 방식은 둘 중 하나입니다. 커널의 cgroup 파일시스템을 직접 만지는 cgroupfs 방식과, systemd에 위임하는 systemd 방식입니다. 호스트에서 systemd가 이미 init으로 cgroup을 관리하고 있으면 관리자가 둘이 되는 셈이라, 쿠버네티스 문서는 systemd 방식으로 통일하기를 권하고 kubeadm도 v1.22부터 kubelet 기본값을 cgroupDriver: systemd로 둡니다.

containerd config default가 만드는 설정에서는 이 값이 false(cgroupfs)로 나옵니다. kubelet은 systemd 방식으로, containerd는 cgroupfs 방식으로 서로 다른 장부를 쓰면 자원 계산이 어긋나 파드가 뜨다가 죽거나 노드가 메모리 압박 상태로 잘못 판정됩니다. 그래서 true로 맞춥니다.

containerd config default > /etc/containerd/config.toml     # 원본은 백업해 두고
sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
nvidia-ctk runtime configure --runtime=containerd
systemctl restart containerd
crictl --runtime-endpoint unix:///run/containerd/containerd.sock info   # CRI 소켓 응답 확인

마지막 줄의 crictl은 CRI 규격으로 런타임에 말을 걸어 보는 도구입니다. kubelet이 하는 것과 같은 방식으로 소켓에 접속하므로, 이 명령이 JSON을 돌려주면 kubelet도 붙을 수 있다고 봐도 됩니다.

nvidia-ctk는 NVIDIA Container Toolkit에 들어 있는 명령줄 도구입니다. 이 툴킷은 컨테이너 안에서 GPU를 쓰기 위한 패키지 묶음으로, 컨테이너 런타임 설정을 손봐 주는 nvidia-ctk와 실제로 GPU 디바이스를 컨테이너에 넣어 주는 nvidia-container-runtime이 함께 들어 있습니다. GX10의 벤더 이미지에는 NVIDIA 드라이버와 이 툴킷이 이미 설치되어 있어서 따로 깔 필요는 없었습니다. nvidia-ctk --version과 nvidia-smi가 정상 응답하면 준비된 것입니다.

nvidia-ctk runtime configure는 GPU용 런타임을 containerd에 등록합니다. 이 도구는 /etc/containerd/config.toml을 직접 수정하지 않습니다. 대신 /etc/containerd/conf.d/ 디렉토리에 99-nvidia.toml이라는 별도 파일을 만들어 GPU 런타임 설정만 거기에 적고, config.toml 맨 위에는 "이 디렉토리의 .toml 파일을 모두 읽어서 합쳐라"는 imports 한 줄만 추가합니다.

# /etc/containerd/config.toml
imports = ["/etc/containerd/conf.d/*.toml"]
version = 3

containerd가 시작할 때 설정을 읽는 순서는 이렇습니다. config.toml을 먼저 읽고, imports에 적힌 경로의 파일들을 차례로 읽어 같은 키가 있으면 나중 값으로 덮어씁니다.

flowchart LR A["/etc/containerd/config.toml<br/>(containerd config default 산출물)"] -->|"imports = [conf.d/*.toml]"| B["/etc/containerd/conf.d/99-nvidia.toml<br/>(nvidia-ctk가 생성)"] A --> C["최종 설정"] B -->|"같은 키는 덮어씀"| C C --> D["containerd 데몬"]

이렇게 나눠 두면 나중에 containerd config default로 메인 설정을 다시 만들어도 GPU 설정은 그대로 남습니다. 파일 이름 앞의 99-는 여러 파일이 있을 때 알파벳 순으로 가장 뒤에 읽히게 하려는 관례입니다.

여기서 한 번 걸렸습니다. 두 파일이 합쳐지는 단위가 문제였습니다.

containerd 설정에는 "컨테이너를 실제로 실행할 프로그램 목록"에 해당하는 runtimes 부분이 있습니다. 기본 설정에는 runc 하나만 들어 있고, nvidia-ctk는 여기에 nvidia를 하나 더 추가합니다. 각 항목마다 어떤 바이너리를 쓸지, cgroup을 어떻게 다룰지(SystemdCgroup) 같은 옵션이 따로 붙습니다.

# 합쳐진 뒤 containerd가 보는 모습 (containerd config dump로 확인)
[plugins."io.containerd.cri.v1.runtime".containerd.runtimes]

  [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.runc]
    runtime_type = "io.containerd.runc.v2"
    [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.runc.options]
      SystemdCgroup = true      # 앞에서 sed로 고친 값

  [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.nvidia]
    runtime_type = "io.containerd.runc.v2"
    [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.nvidia.options]
      BinaryName = "/usr/bin/nvidia-container-runtime"
      SystemdCgroup = true      # 99-nvidia.toml이 가져온 값

99-nvidia.toml이 config.toml 위에 덮어씌워질 때, SystemdCgroup 같은 키 하나만 바꾸는 게 아니라 runtimes 아래 전체를 통째로 바꿉니다. 그래서 99-nvidia.toml에 nvidia 항목만 있으면 config.toml에 있던 runc 항목이 사라지고, runc가 있어도 그쪽 SystemdCgroup이 false면 앞에서 sed로 고친 값이 무효가 됩니다. runc와 nvidia 두 항목이 99-nvidia.toml 안에 모두 들어 있고 둘 다 SystemdCgroup = true인지 확인해야 합니다. 저는 containerd config dump | grep -A3 runtimes.runc로 최종 결과를 보고 잡았습니다.

💡 설정을 건드리기 전에 nvidia-ctk runtime configure --dry-run을 돌리면 어떤 파일에 무엇이 추가되는지 미리 볼 수 있습니다. 이미 손으로 고쳐 둔 설정이 있을 때 특히 유용했습니다.


3. 노드 IP가 Tailscale 주소로 잡혔다

조인 자체는 성공했습니다. kubectl get nodes에 gx10이 나타났지만 상태가 NotReady에 머물렀고, kube-system의 cilium-agent 파드가 그 노드에서 계속 재시작했습니다. 노드는 CNI 플러그인이 정상적으로 올라와야 Ready가 되기 때문에 먼저 cilium 파드의 로그를 보려고 했는데, 로그 대신 이런 에러가 나왔습니다.

Error from server: Get "https://100.87.0.2:10250/containerLogs/...": dial tcp 100.87.0.2:10250: i/o timeout

kubectl logs는 kubectl이 노드에 직접 접속하는 게 아니라, API 서버가 대신 해당 노드의 kubelet(10250 포트)에 접속해 로그를 받아 옵니다. 이때 API 서버는 Node 오브젝트의 status.addresses에 등록된 InternalIP로 kubelet을 찾습니다. 에러 메시지의 100.87.0.2가 바로 그 주소인데, 이 장비에 설치되어 있던 Tailscale(WireGuard 기반 개인 VPN, 100.x.y.z 대역을 씁니다)의 주소였습니다.

kubelet에 --node-ip를 명시하지 않으면 kubelet이 스스로 고릅니다. 먼저 호스트 이름을 DNS나 /etc/hosts로 풀어 보고, 그게 안 되면 호스트의 네트워크 인터페이스를 훑어 하나를 택합니다. 이 선택이 관리자가 기대하는 "LAN 주소"와 일치한다는 보장은 없습니다. 이 장비에는 LAN 인터페이스(enP7s7) 말고도 Tailscale의 tailscale0, Docker가 만든 docker0, Cilium이 만든 cilium_host가 함께 올라와 있었고, 그중 Tailscale 주소가 선택됐습니다.

$ ip -4 -o addr show | awk '{print $2, $4}'
lo 127.0.0.1/8
enP7s7 10.0.0.33/24
tailscale0 100.87.0.2/32
docker0 172.17.0.1/16
cilium_host 172.20.6.97/32

InternalIP는 API 서버만 쓰는 값이 아닙니다. Cilium도 다른 노드로 파드 트래픽을 보낼 때 각 노드의 InternalIP를 목적지로 삼습니다. 나머지 여섯 대는 LAN에만 있고 Tailscale에 들어와 있지 않으니, API 서버든 다른 노드의 cilium이든 100.87.0.2로는 닿을 수 없습니다. kubectl logs가 timeout으로 실패한 것도, cilium이 노드 간 연결을 맺지 못해 재시작을 반복한 것도, 그래서 노드가 Ready가 되지 않은 것도 전부 이 한 값에서 나왔습니다.

kubelet에 노드 IP를 못 박아 해결했습니다. 1절의 파일에 인자를 하나 더 붙이고 kubelet을 재시작하면, kubelet이 다시 올라오면서 노드 상태를 새 주소로 갱신합니다.

# /etc/default/kubelet
KUBELET_EXTRA_ARGS=... --node-ip=10.0.0.33
systemctl restart kubelet
$ kubectl get node gx10 -o jsonpath='{.status.addresses}'
[{"address":"10.0.0.33","type":"InternalIP"},{"address":"gx10","type":"Hostname"}]

VPN 주소는 노드 IP로 쓸 수 없다는 게 결론이었습니다. 클러스터의 모든 노드가 같은 오버레이에 들어와 있다면 이야기가 다르겠지만, 일부만 들어와 있으면 도달성이 비대칭이 됩니다. 인터페이스가 여러 개인 호스트를 조인할 때는 --node-ip를 처음부터 적어 두는 편이 안전하다고 판단했습니다.


4. Cilium이 direct routing device를 찾지 못했다

노드 IP를 고치고 나니 cilium-agent가 다른 이유로 죽었습니다.

level=fatal msg="unable to determine direct routing device"

에러를 이해하려면 이 클러스터의 Cilium이 파드 트래픽을 어떻게 옮기는지부터 봐야 합니다. CNI가 노드 사이로 파드 패킷을 넘기는 방식은 크게 둘입니다.

  • tunnel 모드(VXLAN/Geneve): 파드 패킷을 노드 IP끼리 주고받는 패킷 안에 한 번 더 감싸서 보냅니다. 물리 네트워크는 노드 IP만 알면 되므로 설정이 간단하지만, 캡슐화 오버헤드가 있습니다.
  • native routing 모드: 파드 IP가 찍힌 패킷을 감싸지 않고 그대로 물리 네트워크에 내보냅니다. 대신 각 노드가 "저 파드 CIDR은 저 노드로 보내라"는 라우팅 테이블을 갖고 있어야 합니다.

이 클러스터는 native routing 모드입니다. 모든 노드가 같은 L2 네트워크(10.0.0.0/24)에 있어 가능한 선택이었고, gx10의 라우팅 테이블에도 Cilium이 넣어 준 경로가 보입니다.

$ ip route
default via 10.0.0.254 dev enP7s7 src 10.0.0.33
172.20.0.0/24 via 10.0.0.111 dev enP7s7
172.20.1.0/24 via 10.0.0.101 dev enP7s7
172.20.2.0/24 via 10.0.0.102 dev enP7s7
...

172.20.N.0/24가 각 노드에 배정된 파드 CIDR이고, via 10.0.0.1xx가 그 노드의 InternalIP입니다. 3절에서 InternalIP가 틀렸을 때 cilium이 재시작을 반복한 이유도 여기에 있습니다. 상대 노드가 닿지 않는 주소를 갖고 있으면 이 경로를 만들 수 없기 때문입니다.

이 구조에서는 파드 트래픽을 어느 물리 인터페이스로 내보낼지 Cilium이 알아야 합니다. Cilium은 이 값을 devices(Cilium이 다룰 인터페이스 목록)와 direct-routing-device(native routing에 쓸 인터페이스) 두 설정으로 받는데, 설정이 없으면 자동 감지를 시도하고 그것도 실패하면 위의 fatal 에러를 내고 종료합니다. 이 클러스터에서는 자동 감지에 맡기지 않고 인터페이스 이름을 명시해 둔 상태였습니다.

Cilium의 전역 설정은 kube-system 네임스페이스의 cilium-config ConfigMap에 들어 있습니다. Helm으로 설치할 때 넘긴 값들이 여기에 key-value로 저장되고, 모든 노드의 cilium-agent가 시작할 때 이 ConfigMap을 읽습니다. 여기에 인터페이스 이름이 고정되어 있었습니다.

$ kubectl get cm -n kube-system cilium-config -o jsonpath='{.data.devices}'
ens18

기존 여섯 대는 전부 Proxmox VM이라 인터페이스 이름이 ens18로 같습니다. gx10에는 그런 이름이 없고 enP7s7입니다. 전역 설정을 바꾸면 다른 여섯 대가 깨지므로, 노드 하나만 다른 값을 쓰게 해야 했습니다.

Cilium은 이 용도로 CiliumNodeConfig를 제공합니다. Cilium 1.13부터 들어온 CRD로, cilium-config의 값을 특정 노드에서만 다른 값으로 바꿔 주는 오버라이드입니다. cilium-agent는 시작할 때 전역 ConfigMap을 먼저 읽고, 자기 노드가 nodeSelector에 걸리는 CiliumNodeConfig가 있으면 그 defaults 아래의 키로 덮어씁니다.

apiVersion: cilium.io/v2
kind: CiliumNodeConfig
metadata:
  name: gx10-net-override
  namespace: kube-system
spec:
  nodeSelector:
    matchLabels:
      kubernetes.io/hostname: gx10
  defaults:
    devices: "enP7s7"
    direct-routing-device: "enP7s7"

agent가 시작 시점에만 이 값을 읽기 때문에, 리소스를 만든 뒤 해당 노드의 cilium 파드를 지워 다시 뜨게 해야 합니다. DaemonSet이 곧바로 새 파드를 만들고, 이번에는 enP7s7을 보고 정상적으로 올라옵니다.

kubectl apply -f cilium-node-config-gx10.yaml
kubectl delete pod -n kube-system -l k8s-app=cilium --field-selector spec.nodeName=gx10
$ kubectl get pods -n kube-system -o wide --field-selector spec.nodeName=gx10
NAME                         READY   STATUS    RESTARTS   AGE     IP
cilium-envoy-sspmk           1/1     Running   0          4d      10.0.0.33
cilium-v7ssb                 1/1     Running   0          3d20h   10.0.0.33
nvidia-device-plugin-fnqw4   1/1     Running   0          3d23h   172.20.6.146

cilium과 cilium-envoy의 IP가 파드 CIDR이 아니라 노드 IP(10.0.0.33)로 나오는 것은 두 파드가 hostNetwork: true로 노드의 네트워크 네임스페이스를 그대로 쓰기 때문입니다. CNI 자신은 CNI가 만들어 주는 네트워크에 의존할 수 없으니 당연한 구성입니다. 반면 nvidia-device-plugin은 일반 파드라 172.20.6.x 대역의 파드 IP를 받았고, 이 값이 보인다는 것 자체가 이 노드에서 Cilium이 파드 네트워크를 정상적으로 배정하기 시작했다는 뜻입니다.

이 리소스를 다루면서 두 가지를 배웠습니다.

하나는 GitOps 쪽입니다. 이 클러스터는 ArgoCD가 git 저장소의 매니페스트와 클러스터의 실제 리소스를 주기적으로 비교하고 있고, Application에 selfHeal: true가 켜져 있어서 두 상태가 어긋나면(drift) 클러스터 쪽을 git 쪽으로 되돌립니다. 그래서 kubectl edit으로 CiliumNodeConfig의 값을 바꾸면 몇 초 안에 원래 값으로 돌아갑니다. 값을 바꾸려면 저장소의 파일을 고쳐 커밋해야 합니다. 라이브 리소스를 고치고 "왜 안 바뀌지" 하며 한참 봤습니다.

다른 하나는 조금 더 아프게 배웠습니다. 이 노드는 처음에 WiFi(wlP9s9)로 붙어 있었고 나중에 유선으로 옮겼는데, 그 과정에서 제가 접속에 쓰고 있던 인터페이스를 내려 버려 원격에서 장비를 잃었습니다. 물리적으로 가서 살렸습니다. 원격으로 네트워크 설정을 바꿀 때는 지금 접속에 쓰고 있는 경로를 먼저 확인하고, 새 경로가 살아 있는 것을 확인한 뒤에 옛 경로를 정리하는 순서를 지켜야 합니다.


5. device plugin이 통합메모리에서 크래시했다

네트워크가 정리되고 노드가 Ready가 됐습니다. 이 시점에서 노드는 일반 파드를 돌릴 수 있지만, 쿠버네티스는 이 노드에 GPU가 있다는 사실을 아직 모릅니다. kubectl describe node gx10의 Allocatable에는 cpu, memory, pods, ephemeral-storage만 있습니다.

쿠버네티스가 CPU와 메모리 외의 하드웨어를 리소스로 다루는 방법이 device plugin입니다. 동작 구조는 이렇습니다.

  1. 벤더가 만든 device plugin이 각 노드에서 DaemonSet으로 돌면서, /var/lib/kubelet/device-plugins/ 아래에 유닉스 소켓을 만들고 kubelet에 "나는 nvidia.com/gpu라는 리소스를 담당한다"고 등록합니다.
  2. 플러그인이 노드의 GPU를 탐지해 목록을 kubelet에 보고하면, kubelet이 Node 오브젝트의 status.allocatable에 nvidia.com/gpu: N을 추가합니다. 이때부터 스케줄러가 이 리소스를 계산에 넣습니다.
  3. 파드가 resources.limits에 nvidia.com/gpu: 1을 적으면, 스케줄러가 잔량이 있는 노드를 골라 배치하고, 그 노드의 kubelet이 플러그인에 Allocate를 호출해 "어느 GPU를 어떻게 컨테이너에 넣을지"(환경변수, 디바이스 파일, 마운트)를 받아 컨테이너 생성에 반영합니다.

NVIDIA가 제공하는 device plugin(k8s-device-plugin)을 DaemonSet으로 올렸는데, 초기화 중에 죽었습니다.

error getting device memory: Not Supported

NVML(NVIDIA Management Library)은 nvidia-smi가 내부적으로 쓰는 드라이버 라이브러리로, device plugin도 이 라이브러리로 GPU 목록과 상태를 읽습니다. 일반적인 GPU는 자기 전용 VRAM이 있어서 "GPU 메모리가 몇 GB냐"는 질문에 답이 정해져 있습니다. GB10은 CPU와 GPU가 121GiB 메모리 한 덩어리를 함께 쓰는 통합메모리 구조라, GPU만의 메모리 크기라는 개념이 없고 해당 NVML 호출이 Not Supported를 돌려줍니다. nvidia-smi에서도 Memory-Usage 칸이 Not Supported로 나오는데, 이 하드웨어에서는 그게 정상 출력입니다. 문제는 device plugin이 그 값을 필수로 읽으려 했고, 실패하면 초기화를 중단하도록 되어 있었다는 점입니다.

플러그인 버전을 올려 해결했습니다. 통합메모리 대응이 v0.17.4에 들어갔고, 저는 v0.18.0을 씁니다.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: nvidia-device-plugin
  namespace: kube-system
spec:
  template:
    spec:
      runtimeClassName: nvidia          # 플러그인 자신도 GPU를 봐야 한다
      nodeSelector:
        gpu: nvidia-gb10
      tolerations:
        - key: dedicated
          operator: Equal
          value: ai-gpu
          effect: NoSchedule
        - key: CriticalAddonsOnly
          operator: Exists
        - key: nvidia.com/gpu
          operator: Exists
          effect: NoSchedule
      priorityClassName: system-node-critical
      containers:
        - name: nvidia-device-plugin-ctr
          image: nvcr.io/nvidia/k8s-device-plugin:v0.18.0
          env:
            - name: FAIL_ON_INIT_ERROR
              value: "true"
          securityContext:
            privileged: true
          volumeMounts:
            - name: device-plugin
              mountPath: /var/lib/kubelet/device-plugins
      volumes:
        - name: device-plugin
          hostPath:
            path: /var/lib/kubelet/device-plugins

필드를 위에서부터 보면 이렇습니다.

  • runtimeClassName: nvidia: 플러그인 자신이 NVML로 GPU를 조회해야 하므로, 컨테이너 안에 드라이버 라이브러리가 들어와 있어야 합니다. 6절에서 다루는 GPU 주입 경로를 플러그인도 똑같이 탑니다.
  • nodeSelector: gpu: nvidia-gb10: 1절에서 kubelet 인자로 붙인 라벨입니다. GPU가 없는 나머지 여섯 대에서는 이 DaemonSet 파드가 만들어지지 않습니다.
  • tolerations: 세 개가 있습니다. 첫 번째 dedicated=ai-gpu는 1절에서 이 노드에 건 taint를 통과하기 위한 것입니다. CriticalAddonsOnly와 nvidia.com/gpu는 NVIDIA가 배포하는 매니페스트에 기본으로 들어 있는 것으로, 이 클러스터에는 해당 taint가 없어서 실제로는 아무 일도 하지 않지만 그대로 두었습니다.
  • priorityClassName: system-node-critical: 노드 자원이 부족할 때 이 파드가 먼저 쫓겨나지 않게 합니다. 플러그인이 죽으면 그 노드의 GPU 리소스가 통째로 사라지기 때문입니다.
  • FAIL_ON_INIT_ERROR: "true": 초기화에 실패하면 조용히 대기하지 말고 종료하라는 옵션입니다. 이 값 덕분에 위의 Not Supported 문제가 CrashLoopBackOff로 눈에 띄었습니다.
  • privileged: true: 호스트의 /dev/nvidia* 디바이스 파일에 접근하기 위해 필요합니다.

/var/lib/kubelet/device-plugins를 hostPath로 마운트하는 것이 이 DaemonSet의 핵심입니다. 플러그인은 이 디렉토리에 유닉스 소켓을 만들고 kubelet에 자신을 등록합니다. 등록이 끝나면 kubelet이 노드 상태에 리소스를 추가합니다.

$ kubectl get node gx10 -o jsonpath='{.status.allocatable}' | jq
{
  "cpu": "20",
  "memory": "127432936Ki",
  "nvidia.com/gpu": "1",
  "pods": "110"
}

nvidia.com/gpu: "1"이 새로 생겼습니다. cpu, memory와 나란히 있는 이 한 줄이 스케줄러가 GPU를 계산에 넣기 시작했다는 표시입니다.

새로 나온 GPU를 쓸 때는 device plugin 버전을 먼저 확인하는 게 좋겠다는 생각이 들었습니다. NVIDIA는 드라이버, Container Toolkit, device plugin을 한 번에 설치·관리해 주는 GPU Operator도 제공하는데, GX10은 드라이버와 툴킷이 OS 이미지에 이미 들어 있어서 이번에는 device plugin만 따로 올렸습니다. GPU Operator를 쓴다면 v25.10.0 이상이 같은 통합메모리 대응을 포함합니다.


6. GPU가 실제로 컨테이너에 붙는지 확인하기

nvidia.com/gpu: 1이 보이기 시작했다고 해서 GPU 파드가 제대로 뜬다는 뜻은 아니었습니다. 조인 과정에서 만진 조각들이 어떻게 이어지는지 한 번 정리해 두는 편이 나았습니다.

flowchart TB A["Pod spec<br/>runtimeClassName: nvidia<br/>limits: nvidia.com/gpu: 1"] --> B["kube-scheduler<br/>노드의 nvidia.com/gpu 잔량 확인"] B --> C["kubelet<br/>device plugin에 Allocate 호출"] C --> D["RuntimeClass nvidia<br/>handler: nvidia"] D --> E["containerd<br/>plugins...runtimes.nvidia"] E --> F["/usr/bin/nvidia-container-runtime"] F --> G["컨테이너에 /dev/nvidia*<br/>+ 드라이버 라이브러리 주입"]

그림을 따라가면 이렇습니다. 파드 스펙에 nvidia.com/gpu: 1을 적으면 스케줄러가 5절에서 등록된 잔량을 보고 노드를 고르고, kubelet이 device plugin의 Allocate를 호출해 어느 GPU를 줄지 결정합니다. 여기까지가 위쪽 갈래로, GPU 점유를 장부에 기록하는 경로입니다. 한편 파드 스펙의 runtimeClassName: nvidia는 kubelet이 containerd에 컨테이너 생성을 요청할 때 "이 컨테이너는 nvidia 핸들러로 만들어라"는 표시로 전달되고, containerd는 자기 설정의 runtimes.nvidia 항목을 찾아 그 바이너리(nvidia-container-runtime)로 컨테이너를 만듭니다. 이 바이너리가 컨테이너 안에 GPU 디바이스 파일과 드라이버 라이브러리를 넣어 줍니다. 이쪽이 아래쪽 갈래로, 디바이스를 실제로 넣는 경로입니다.

이 두 갈래가 서로를 확인하지 않고 독립적으로 동작한다는 점이 곧 문제를 만듭니다.

RuntimeClass는 "이 파드는 어떤 컨테이너 런타임 설정으로 만들 것인가"를 파드 단위로 고르게 해 주는 클러스터 리소스입니다. 보통은 gVisor나 Kata처럼 격리 수준이 다른 런타임을 고르는 데 쓰이는데, 여기서는 같은 runc 계열이지만 GPU를 넣어 주는 변형을 고르는 용도로 씁니다. 리소스 자체는 세 줄입니다.

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: nvidia
handler: nvidia

handler 값에 특별한 의미는 없습니다. CRI 런타임에 전달되는 문자열일 뿐이고, containerd가 이 이름으로 자기 설정에서 섹션을 찾습니다. 2절에서 nvidia-ctk가 99-nvidia.toml에 만들어 둔 것이 바로 그 섹션입니다.

# /etc/containerd/conf.d/99-nvidia.toml (runc 항목은 생략)
[plugins."io.containerd.cri.v1.runtime".containerd.runtimes.nvidia]
  runtime_type = "io.containerd.runc.v2"

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

여기서 runc가 무엇인지 짚어 두면 이해가 쉽습니다. containerd는 이미지를 풀고 컨테이너의 생애주기를 관리하는 상위 데몬이고, 리눅스 네임스페이스와 cgroup을 실제로 만들어 프로세스를 격리하는 마지막 한 걸음은 runc라는 별도 프로그램이 합니다. containerd가 "이런 컨테이너를 만들어라"는 명세(OCI 스펙, config.json)를 써 주면 runc가 그대로 실행합니다.

runtime_type은 기본 runc와 똑같습니다. 달라지는 것은 BinaryName 하나입니다. nvidia-container-runtime은 runc를 대체하는 물건이 아니라, containerd가 넘긴 config.json을 받아 GPU 디바이스 파일(/dev/nvidia*)과 호스트의 드라이버 라이브러리(libcuda.so 등)를 마운트 목록에 끼워 넣은 뒤 진짜 runc를 호출하는 얇은 래퍼입니다. 그래서 컨테이너 이미지에 드라이버가 들어 있지 않아도 실행 시점에 호스트 드라이버가 들어옵니다. CUDA 이미지가 드라이버 버전에 묶이지 않는 이유입니다.

그래서 GPU 파드에 필요한 것이 세 줄이 됩니다.

spec:
  runtimeClassName: nvidia              # 주입 경로
  tolerations:                          # 전용 노드에 들어갈 자격
    - key: dedicated
      operator: Equal
      value: ai-gpu
      effect: NoSchedule
  nodeSelector:
    gpu: nvidia-gb10
  containers:
    - name: app
      resources:
        limits:
          nvidia.com/gpu: 1             # 회계

둘 다 있어야 한다는 건 짐작이 갔는데, 하나만 빠졌을 때 어떻게 되는지가 직관과 달라서 직접 확인해 봤습니다. 같은 CUDA 이미지로 파드 세 개를 만들되 runtimeClassName과 limits의 조합만 달리했습니다. 각 파드에서 /dev/nvidia* 디바이스 파일이 보이는지, 그리고 nvidia-smi -L(장착된 GPU 목록 출력)이 동작하는지로 GPU가 들어왔는지를 판단했습니다.

케이스 A: runtimeClassName 없이

$ kubectl exec -n llm gpu-case-norc -- sh -c 'ls /dev/nvidia*; nvidia-smi -L'
ls: cannot access '/dev/nvidia*': No such file or directory
/bin/bash: line 1: nvidia-smi: command not found

runtimeClassName이 없으면 containerd 기본 런타임인 runc로 실행됩니다. /dev/nvidia*가 없다는 것은 디바이스 파일이 마운트되지 않았다는 뜻이고, nvidia-smi: command not found는 호스트 드라이버 라이브러리가 들어오지 않았다는 뜻입니다(nvidia-smi 바이너리 자체가 드라이버와 함께 주입됩니다). 예상대로입니다.

케이스 B: runtimeClassName만 주고 리소스는 요청하지 않았을 때

$ kubectl exec -n llm gpu-case-withrc -- sh -c 'ls /dev/nvidia*; nvidia-smi -L'
/dev/nvidia-modeset
/dev/nvidia-uvm
/dev/nvidia-uvm-tools
/dev/nvidia0
/dev/nvidiactl
GPU 0: NVIDIA GB10 (UUID: GPU-5b30d1b2-8a13-9085-9802-88c1f3626f29)

GPU가 그대로 들어왔습니다. nvidia.com/gpu를 한 개도 요청하지 않았는데 nvidia-smi가 물리 GPU를 인식합니다.

원인은 이미지에 박혀 있는 환경변수였습니다.

$ kubectl exec -n llm gpu-case-withrc -- env | grep NVIDIA_
NVIDIA_VISIBLE_DEVICES=all
NVIDIA_REQUIRE_CUDA=cuda>=9.0
NVIDIA_DRIVER_CAPABILITIES=compute,utility,video

NVIDIA_VISIBLE_DEVICES는 nvidia-container-runtime이 "이 컨테이너에 어느 GPU를 넣을까"를 결정할 때 읽는 환경변수입니다. 원래 설계는 device plugin이 Allocate 응답으로 이 변수에 배정된 GPU의 UUID를 채워 넣고, 런타임은 그 GPU만 넣어 주는 흐름입니다. 그런데 NGC에서 배포하는 CUDA 계열 이미지는 대부분 Dockerfile에 ENV NVIDIA_VISIBLE_DEVICES=all이 박혀 있습니다. Docker에서 --gpus all로 쓰던 편의를 위한 기본값인데, 쿠버네티스에서도 이 값이 컨테이너 환경변수로 그대로 들어가고 nvidia-container-runtime은 출처를 가리지 않고 이 값을 신뢰합니다. device plugin이 아무 GPU도 배정하지 않았는데 이미지가 스스로 all을 요구한 셈이고, 런타임은 그 요구대로 노드의 GPU를 전부 넣어 줬습니다.

# /etc/nvidia-container-runtime/config.toml
#accept-nvidia-visible-devices-envvar-when-unprivileged = true
mode = "auto"

주석 처리되어 있으니 기본값 true가 적용됩니다. 이 옵션은 이름 그대로 privileged가 아닌 컨테이너에서도 이미지가 가져온 NVIDIA_VISIBLE_DEVICES 값을 받아들이겠다는 뜻입니다. NVIDIA 문서는 이 우회를 막고 싶으면 이 값을 false로 바꾸고, device plugin이 배정 결과를 환경변수 대신 볼륨 마운트로 전달하게(--device-list-strategy=volume-mounts) 바꾸는 방법을 안내합니다.

이 상태가 까다롭습니다. 파드는 GPU를 물리적으로 쓰고 있는데 스케줄러 장부에는 아무 기록이 없습니다. 실제로 위 실험을 돌리던 시점에 GPU는 다른 파드가 점유하고 있었고, 그 위에 실험용 파드가 그대로 올라탔습니다. 리소스를 요청하지 않은 파드 하나가 운영 중인 워크로드와 VRAM을 놓고 경쟁하게 된 셈입니다.

케이스 C: 리소스까지 요청했을 때

$ kubectl describe pod -n llm gpu-case-limit | grep -A 3 '^Events:'
Events:
  Type     Reason            Age   From               Message
  ----     ------            ----  ----               -------
  Warning  FailedScheduling  9s    default-scheduler  0/7 nodes are available:
    1 Insufficient nvidia.com/gpu, 3 node(s) didn't match Pod's node affinity/selector,
    3 node(s) had untolerated taint {node-role.kubernetes.io/control-plane: }.

이벤트를 읽으면 후보 노드 7대가 전부 탈락한 이유가 나옵니다. control-plane 3대는 node-role.kubernetes.io/control-plane taint를 toleration하지 않아 제외, worker 3대는 nodeSelector: gpu=nvidia-gb10에 맞지 않아 제외, 남은 gx10 한 대는 GPU 잔량이 0이라 Insufficient nvidia.com/gpu로 제외됐습니다. GPU가 이미 배정되어 있다는 사실을 스케줄러가 알고 막아 준 것이고, 이것이 정상 동작입니다.

세 케이스를 놓고 보면 runtimeClassName은 GPU가 컨테이너에 들어오게 하고, limits는 스케줄러가 그 사실을 알게 합니다. 눈에 보이는 증상(nvidia-smi가 되느냐)만으로는 limits 누락이 드러나지 않기 때문에, 저는 이 두 줄을 항상 붙여 다니는 한 쌍으로 취급하기로 했습니다.


7. 첫 워크로드를 올리며 추가로 걸린 것

노드가 준비된 뒤 첫 워크로드로 vLLM을 올려 gpt-oss-120b를 서빙했습니다. 여기서도 이 노드의 특성 때문에 몇 가지가 더 나왔습니다.

arm64 이미지가 필요합니다. gx10은 CPU가 arm64이고, GPU의 compute capability(NVIDIA가 GPU 세대별 명령어 집합을 구분하는 번호로, 빌드 시 sm_XX로 지정합니다)는 12.1(sm_121a)입니다. 컨테이너 이미지는 CPU 아키텍처별로 따로 빌드되기 때문에 x86_64용 이미지는 이 노드에서 exec format error로 실행조차 되지 않고, PyTorch나 vLLM 같은 라이브러리도 sm_121a용으로 컴파일된 빌드가 들어 있어야 GPU 커널이 돕니다. 일반 PyPI 휠이나 대부분의 커뮤니티 이미지가 x86_64와 기존 세대 GPU를 전제로 만들어져 있어 쓸 수 없었고, NGC의 nvcr.io/nvidia/vllm:25.12.post1-py3을 썼습니다. 새 아키텍처의 GPU에서는 이미지 선택 자체가 첫 번째 제약이 됩니다.

GPU를 쪼갤 수 없습니다. MIG(Multi-Instance GPU)는 A100·H100 같은 데이터센터 GPU를 하드웨어 수준에서 최대 7개의 독립된 조각으로 나눠, 각 조각을 별도의 nvidia.com/mig-* 리소스로 노출하는 기능입니다. 이게 있으면 GPU 하나에 파드 여러 개를 메모리 격리까지 된 상태로 올릴 수 있습니다. DGX Spark 계열은 데스크탑 SoC라 이 파티셔닝 기능 자체가 없어서, nvidia.com/gpu: 1을 요구하는 워크로드는 한 번에 하나만 뜹니다. 저는 vLLM과 ComfyUI를 교대로 돌리는데, GitOps 클러스터라 kubectl scale로 바꾸면 selfHeal이 되돌리므로 매니페스트를 커밋해야 반영됩니다. 여기에 따라오는 설정이 하나 더 있습니다.

spec:
  strategy:
    type: Recreate

Deployment의 기본 전략 RollingUpdate는 maxSurge: 25%, maxUnavailable: 25%가 기본값이고, replica가 1이면 올림 처리되어 새 파드 1개를 먼저 띄우고 그것이 Ready가 된 뒤 옛 파드를 지웁니다. 그런데 새 파드가 요구하는 GPU 1개를 옛 파드가 쥐고 있으니 새 파드는 Insufficient nvidia.com/gpu로 Pending에 걸리고, 옛 파드는 새 파드가 Ready가 되기를 기다리며 계속 살아 있어 롤아웃이 그 자리에서 멈춥니다. Recreate는 옛 파드를 먼저 전부 지운 뒤 새 파드를 만들기 때문에 이 교착이 없습니다. 잠깐의 다운타임은 생기지만, GPU가 하나뿐인 노드에서는 다른 선택이 없습니다.

모델 로딩 시간에 프로브를 맞춰야 합니다. 처음에 기본 프로브 설정으로 두었더니 컨테이너가 exitCode 137로 죽었는데, 로그에는 모델을 로드하는 중이라는 메시지밖에 없었습니다. 137은 128 + 9, 즉 프로세스가 시그널 9(SIGKILL)로 죽었다는 뜻입니다. OOM killer가 죽였을 때도 같은 코드가 나오기 때문에 메모리를 먼저 의심하기 쉬운데, 둘은 kubectl describe pod의 이벤트로 구분할 수 있습니다. OOM이면 컨테이너 상태에 OOMKilled가, 프로브 실패면 Unhealthy와 Killing 이벤트가 남습니다. 이번 범인은 kubelet이었습니다. startupProbe가 허용한 시간 안에 /health가 응답하지 않자 컨테이너를 죽이고 재시작한 것입니다.

쿠버네티스의 프로브는 셋입니다. startupProbe는 "기동이 끝났는가", readinessProbe는 "트래픽을 받을 준비가 됐는가", livenessProbe는 "살아 있는가"를 봅니다. startupProbe가 성공하기 전까지 나머지 둘은 동작하지 않으므로, 기동이 오래 걸리는 앱은 startupProbe에 넉넉한 시간을 주고 liveness는 짧게 유지하는 조합이 맞습니다.

startupProbe:
  httpGet:
    path: /health
    port: 8000
  periodSeconds: 15
  failureThreshold: 480      # 최대 2시간

periodSeconds × failureThreshold가 최악의 로딩 시간보다 넉넉해야 합니다. startupProbe가 통과하기 전에는 readiness와 liveness가 동작하지 않으므로, 이 값을 크게 잡아도 정상 운영 중의 감지 주기에는 영향이 없습니다.

모델 가중치 자체는 노드 로컬 NVMe에 미리 받아 두고, 그 디렉토리를 파드에 볼륨으로 마운트해 오프라인으로만 로드하게 고정했습니다. HF_HOME=/cache는 Hugging Face 라이브러리가 모델을 찾고 저장하는 캐시 디렉토리를 그 마운트 지점으로 돌리는 설정이고, HF_HUB_OFFLINE=1은 캐시에 없으면 다운로드를 시도하지 말고 바로 실패하라는 설정입니다. 60GB가 넘는 파일을 파드 기동 중에 받게 두면 중간에 한 번 정체되는 것만으로 기동이 통째로 멈춥니다. 모델 캐시는 네트워크 스토리지보다 GPU 노드의 로컬 디스크에 두는 편이 로딩 속도에서도 유리했습니다.

Service 이름이 앱 설정과 충돌했습니다. vLLM Deployment와 Service를 한 번에 올렸더니 파드가 기동 즉시 죽었습니다.

ValueError: VLLM_PORT 'tcp://10.104.169.66:8000' appears to be a URI.
This may be caused by a Kubernetes service discovery issue, ...

설정한 적 없는 VLLM_PORT가 원인이었고, 값에 들어 있는 IP는 방금 만든 Service의 ClusterIP였습니다.

이 동작은 쿠버네티스 초기부터 있던 기능입니다. kubelet은 파드를 만들 때 같은 네임스페이스에 이미 존재하는 ClusterIP Service마다 환경변수 한 묶음을 컨테이너에 넣어 줍니다. 형식은 Docker의 옛 --link 기능을 흉내 낸 것으로, Service 이름을 대문자로 바꾸고 -를 _로 치환한 것이 접두사가 됩니다. 예를 들어 vllm이라는 Service가 8000 포트로 있으면 이런 변수들이 들어갑니다.

VLLM_SERVICE_HOST=10.104.169.66
VLLM_SERVICE_PORT=8000
VLLM_PORT=tcp://10.104.169.66:8000
VLLM_PORT_8000_TCP=tcp://10.104.169.66:8000
VLLM_PORT_8000_TCP_PROTO=tcp
VLLM_PORT_8000_TCP_PORT=8000
VLLM_PORT_8000_TCP_ADDR=10.104.169.66

이 중 <NAME>_PORT만 값이 포트 번호가 아니라 tcp://IP:PORT 형태의 URI입니다. 그런데 vLLM은 분산 실행 시 내부 통신 포트의 시작값을 VLLM_PORT라는 환경변수에서 읽습니다. 제가 설정한 적 없는 VLLM_PORT가 kubelet에 의해 URI 값으로 들어갔고, vLLM이 이걸 정수로 파싱하다 죽은 것입니다. 파드가 Service보다 먼저 만들어졌다면 이 변수가 없어서 정상 기동했을 텐데, 둘을 한 번에 올려 Service가 먼저 생기면서 재현됐습니다.

Service 이름을 vllm-svc로 옮기고, 파드 템플릿에서 링크 주입 자체도 껐습니다.

spec:
  enableServiceLinks: false

enableServiceLinks는 PodSpec의 정식 필드이고 기본값이 true입니다. 껐을 때 같은 네임스페이스 Service의 링크 env는 사라지지만 KUBERNETES_SERVICE_HOST 계열은 남습니다. kubelet이 default 네임스페이스의 kubernetes Service만은 예외로 항상 주입하기 때문에, in-cluster kubeconfig를 쓰는 워크로드는 영향을 받지 않습니다. 클러스터 DNS도 무관하므로 링크 env를 직접 읽는 오래된 이미지가 아니라면 껐을 때 잃는 것이 없다고 봅니다.


8. 최종 노드 구성

조인이 끝난 뒤 gx10에 남은 설정을 모으면 이렇습니다.

위치 설정
/etc/default/kubelet --register-with-taints=dedicated=ai-gpu:NoSchedule, --node-labels=node-type=ai-gpu,gpu=nvidia-gb10, --node-ip=10.0.0.33
/etc/containerd/config.toml containerd config default 산출물 + SystemdCgroup = true + imports
/etc/containerd/conf.d/99-nvidia.toml runtimes.runc + runtimes.nvidia(→ nvidia-container-runtime), 둘 다 SystemdCgroup = true
클러스터 RuntimeClass/nvidia
클러스터 DaemonSet/nvidia-device-plugin v0.18.0 (gx10 전용)
클러스터 CiliumNodeConfig/gx10-net-override (devices: enP7s7)

노드 쪽 설정은 kubectl로 직접 넣었다가 나중에 GitOps 저장소로 옮겼습니다. 이 클러스터의 나머지가 전부 ArgoCD로 관리되고 있어서, 노드 하나만 손으로 유지하면 다음에 같은 작업을 할 때 기억에 의존하게 됩니다.


정리

  1. 벤더가 만든 OS 이미지에 Docker가 미리 깔려 있으면, 함께 들어온 containerd.io 패키지의 설정이 disabled_plugins = ["cri"]라 kubelet이 붙지 못합니다. containerd config default로 다시 만들면 CRI가 켜집니다.
  2. nvidia-ctk runtime configure가 만드는 conf.d/99-nvidia.toml은 config.toml의 런타임 목록(runtimes)을 통째로 덮어씁니다. runc와 nvidia 두 항목이 그 파일 안에 모두 있고 둘 다 SystemdCgroup = true인지 containerd config dump로 확인해야 합니다.
  3. 인터페이스가 여러 개인 호스트는 kubelet이 노드 IP를 잘못 고를 수 있습니다. 이 노드에서는 Tailscale 주소가 선택되어 나머지 노드가 kubelet에 닿지 못했고, --node-ip로 못 박아 해결했습니다.
  4. native routing 모드의 Cilium은 인터페이스 이름을 설정으로 받습니다. 노드마다 이름이 다르면 전역 ConfigMap 대신 CiliumNodeConfig로 그 노드만 덮어쓰는 방법이 있습니다.
  5. GitOps로 관리되는 리소스는 kubectl edit으로 바꿔도 selfHeal이 되돌립니다. 저장소를 고쳐야 반영됩니다.
  6. 통합메모리 GPU는 NVML 메모리 조회가 동작하지 않아 device plugin v0.17.4 미만이 크래시합니다. nvidia-smi의 Not Supported 출력은 이 하드웨어에서 정상입니다.
  7. GPU 파드는 runtimeClassName과 resources.limits가 서로 다른 일을 합니다. 앞의 것만 있어도 NGC 이미지의 NVIDIA_VISIBLE_DEVICES=all 때문에 GPU가 들어오지만, 스케줄러 장부에는 기록이 없어 다른 워크로드와 조용히 간섭합니다.
  8. MIG를 지원하지 않는 GPU에서는 워크로드를 교대로 돌려야 하고, Deployment에 strategy: Recreate가 필요합니다.
  9. 대용량 모델은 startupProbe 허용 시간을 로딩 시간에 맞춰 늘려야 합니다. 넘기면 kubelet이 SIGKILL로 죽이고 로그에는 로딩 중이라는 메시지만 남습니다.
  10. Service 이름이 애플리케이션의 <PREFIX>_PORT 환경변수와 겹치면 kubelet의 서비스 링크 주입이 설정을 덮어씁니다. 이름을 피하거나 enableServiceLinks: false로 막을 수 있습니다.

관련 포스트