MOMIN09

k3s 클러스터 구성

9 min read

구성 개요와 결과

WSL2 Ubuntu 26.04에 systemd 기반 single-node k3s cluster를 구성하고 RTX 4090을 Kubernetes resource로 연결했다. k3s는 control-plane과 embedded containerd를 하나의 service로 실행하며, 기본 ingress와 service load balancer는 제외했다.

WSL2 Ubuntu 26.04
→ systemd k3s server
→ embedded containerd
→ RuntimeClass/nvidia
→ NVIDIA Device Plugin
→ allocatable nvidia.com/gpu: 1
→ GPU workload

2026-07-15에 Docker Desktop 9p mount 문제를 복구한 뒤, NVIDIA Container Toolkit 1.19.1, k3s embedded containerd의 nvidia runtime, RuntimeClass/nvidia, NVIDIA Device Plugin rollout, Node allocatable GPU 1을 실제로 확인했다.

2026-07-20 재부팅 후 같은 mount 형식 오류가 재발했지만 문제 mount를 제거한 뒤 k3s service, control-plane Node, vLLM과 monitoring Pod가 다시 정상 실행되는 것을 확인했다. CUDA sample의 Test PASSED 원문은 보관되지 않았지만, 같은 날 사용자가 Step 2 완료를 최종 확인했다.

Active: active (running)
momindesktop   Ready   control-plane   v1.36.2+k3s1
containerd://2.3.2-k3s2
nvidia-container-toolkit 1.19.1
RuntimeClass/nvidia
allocatable nvidia.com/gpu: 1

1. k3s single-node cluster 구성

k3s stable channel의 single-node server를 다음 설정으로 설치했다.

sudo env \
  INSTALL_K3S_CHANNEL=stable \
  INSTALL_K3S_EXEC="server --disable traefik --disable servicelb --write-kubeconfig-mode 0644" \
  sh /tmp/install-k3s.sh
설정값목적
channelstablestable k3s release 설치
roleserversingle-node control-plane 구성
Traefikdisabled이번 GPU serving 범위에서 ingress 제외
ServiceLBdisabledlocal single-node 환경에서 불필요한 load balancer 제외
kubeconfig mode0644cluster 조회용 kubeconfig 읽기 허용
container runtimek3s embedded containerdDocker가 아닌 k3s 내부 runtime 사용

설치 결과 k3s v1.36.2+k3s1, containerd 2.3.2-k3s2, momindesktop control-plane Node Ready를 확인했다.

2. k3s 기동 트러블슈팅

증상

k3s 설치 직후 systemd service가 restart를 반복했다.

Process: ... ExecStart=/usr/local/bin/k3s server \
  --disable traefik --disable servicelb --write-kubeconfig-mode 0644
(code=exited, status=1/FAILURE)

systemctl status의 status code만으로는 원인을 알 수 없었다. k3s journal의 마지막 오류가 핵심이었다.

Failed to start ContainerManager
err="system validation failed - wrong number of fields (expected 6, got 7)"

원인 확인

Kubelet은 /proc/mounts의 행을 6개 필드로 해석한다. WSL에 연결된 Docker Desktop이 아래 9p mount를 추가했고, Windows 설치 경로의 공백 때문에 7개 필드로 인식됐다.

C:\134Program\040Files\134Docker\134Docker\134resources /Docker/host 9p \
rw,noatime,aname=drvfs;path=C:\Program Files\Docker\Docker\resources;...

이 명령으로 비정상 행을 찾았다.

awk 'NF != 6 {print NR ": fields=" NF ":"; print}' /proc/mounts

출력에서 /Docker/host가 fields=7로 나타났다. NVIDIA GPU 또는 k3s containerd 설정이 원인이 아니었다.

복구

Docker Desktop이 만든 문제 mount만 해제한 뒤 k3s를 재시작했다.

sudo umount /Docker/host
sudo systemctl restart k3s
sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide

복구 후 service가 active (running)이 되었고, momindesktop control-plane Node가 Ready가 됐다.

재발 조건

Docker Desktop을 재시작하거나 WSL integration 상태가 바뀌면 /Docker/host mount가 다시 생성될 수 있다. k3s가 같은 오류로 실패하면 먼저 /proc/mounts 검사를 반복한다. Docker Desktop의 전역 runtime 설정 변경이나 WSL Linux display driver 설치는 이 문제의 해결책으로 사용하지 않았다.

journalctl로 k3s 로그 읽기

journalctl은 systemd가 관리하는 서비스의 journal log를 조회하는 명령이다. k3s는 systemd service이므로 다음처럼 service 단위로 확인한다.

# 현재 boot 이후 k3s 로그 마지막 160줄
journalctl -u k3s -b --no-pager -n 160
 
# 현재 boot의 끝부분부터 전체 로그 확인
sudo journalctl -u k3s -b -e --no-pager
 
# 실시간 로그 추적. Ctrl+C로 종료
sudo journalctl -u k3s -f
option의미
-u k3sk3s.service log만 선택
-b현재 부팅 이후 기록만 선택
-n 160최근 160줄 출력
-e로그 마지막으로 이동
-f새 로그를 계속 출력

3. NVIDIA Container Toolkit 구성

내부 Runbook의 설치 후 검증 명령을 실행했다.

command -v nvidia-container-runtime
command -v nvidia-ctk
nvidia-ctk --version
key값해석
nvidia-container-runtime/usr/bin/nvidia-container-runtimeNVIDIA OCI runtime 실행 파일 확인
nvidia-ctk/usr/bin/nvidia-ctkToolkit 설정 CLI 확인
Toolkit version1.19.1Runbook에서 고정한 version과 일치
commit09ceee5dde66ba9ce25c7cc69b1ebd5e6e3266fa실행한 Toolkit build 식별자

4. k3s NVIDIA runtime과 RuntimeClass 구성

sudo grep -n nvidia /var/lib/rancher/k3s/agent/etc/containerd/config.toml
sudo k3s kubectl get runtimeclass nvidia
key값해석
containerd runtimenvidiak3s embedded containerd가 NVIDIA runtime을 탐지함
runtime binary/usr/bin/nvidia-container-runtime실제 runtime 실행 파일 연결 확인
RuntimeClass namenvidiaPod의 runtimeClassName에 사용할 이름
handlernvidiaRuntimeClass가 containerd의 NVIDIA handler를 선택

5. NVIDIA Device Plugin과 Node GPU 구성

sudo k3s kubectl -n kube-system rollout status \
  daemonset/nvidia-device-plugin-daemonset \
  --timeout=5m
sudo k3s kubectl get nodes \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.allocatable.nvidia\.com/gpu}{"\n"}{end}'
key값해석
Device Plugin rolloutsuccessfully rolled outDaemonSet 배포 완료
Nodemomindesktopsingle-node control plane
nvidia.com/gpu1Scheduler가 할당할 수 있는 GPU 1개 노출

이 결과로 Toolkit 설치만 된 상태가 아니라 NVIDIA runtime → RuntimeClass → Device Plugin → Node allocatable resource 연결이 실제 cluster에 반영됐음을 확인했다.

6. 재부팅 후 cluster 상태 확인

2026-07-20에 k3s service와 cluster resource를 다시 조회했다.

sudo systemctl status k3s --no-pager
k3s --version
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A
key값해석
k3s serviceactive (running)mount 오류 복구 후 service 정상 유지
k3s versionv1.36.2+k3s1실제 실행 version
container runtimecontainerd://2.3.2-k3s2k3s embedded containerd
Nodemomindesktop, Readycontrol-plane Node 정상
vLLM Pod1/1 Running, restart 0재기동 후 Gemma 4 workload 정상
Device Plugin Pod1/1 RunningNVIDIA resource 광고 component 정상
monitoring Pods모두 RunningPrometheus, Grafana, DCGM 구성 복구

일부 system Pod와 monitoring Pod의 restart 횟수는 재부팅 과정의 과거 재시작 기록이며, 현재 상태는 모두 Running이다.

그래프 뷰

백링크