IL-0138 Barush Mendez · 2025-03-03kubernetes

nvidia-dkms-390 드라이버 빌드 실패로 망가진 커널 헤더가 몇 주 동안 방치됐다가, 정전 뒤 재부팅하자 하나뿐인 마스터 노드가 커널 패닉에 빠져 홈랩 쿠버네티스 클러스터가 6일 동안 멈췄다.

쿠버네티스 마스터 노드에는 Jellyfin 하드웨어 가속용 Nvidia GPU 가 달려 있었다. nvidia-dkms-390 드라이버를 설치할 때 드라이버가 기존 커널 버전에 맞게 빌드되지 않았고, 커널 헤더와 다른 의존 패키지도 설정에 실패했다. 이 상태가 몇 주 동안 방치됐지만 시스템은 계속 돌았다.

정전으로 노드가 재부팅되자 커널 패닉이 나서 부팅되지 않았다. 이 노드는 클러스터의 유일한 마스터 노드였다. 쿠버네티스 관리가 전부 멈췄고, 서비스들이 마스터 노드의 사설 IP 를 쓰고 있었기 때문에 모든 애플리케이션에 접속할 수 없었다.

모니터를 연결해 커널 패닉을 확인한 뒤 이전 커널 버전으로 부팅하자 시스템이 돌아왔다. apt update 와 apt upgrade 는 망가진 패키지 때문에 실패했다. 망가진 Nvidia 패키지를 지우고, 패키지 설정과 빠진 의존성을 고치고, 커널 헤더를 다시 설치한 뒤 재부팅해 문제를 해결했다. 자동 알림과 모니터링이 없어서 복구까지 6일이 걸렸다. 데이터 손실은 없었다.

심각도: –
영향 범위: 100% of hosted services unavailable and the Kubernetes API down for 6 days (V-Rising server, Grafana, Jellyfin, Linkding)
영향 사용자: Homelab users; no financial impact
지역: –
감지까지: 3h
복구까지: 6d

증상

2025년 3월 3일 14:15:34부터 홈랩 쿠버네티스에 올린 서비스에 접속되지 않았다. 운영자가 서비스에 들어가려다 직접 알아챘고, 알아채기까지 3시간이 걸렸다.

멈춘 것은 V-Rising 서버, Kube-API, Grafana, Jellyfin, Linkding 이었다. 올린 서비스 전부가 접속되지 않았고, Kube-API 도 내려가 쿠버네티스를 관리할 수 없었다.

원격 접속도 되지 않았다. 마스터 노드에 모니터를 연결해 부팅 로그를 보고 나서야 커널 패닉을 확인했다.

증상 컨트롤 플레인 무응답 서비스 중단 모니터링 중단

원인

원인 소프트웨어 결함

구성 요소 GPU 드라이버 리눅스 커널 쿠버네티스 API 서버

기여 요인 초기 신호 무시

감지

운영자가 서비스에 접속하려다 직접 알아챘다. 자동 알림이 없어서 알아채기까지 3시간이 걸렸다.

조치

원격 접속이 되지 않아 모니터를 연결해 부팅 로그를 보고 커널 패닉을 확인했다.
이전 커널 버전으로 부팅해 시스템을 되살렸다.
sudo apt-get remove --purge '^nvidia-.*' 로 망가진 패키지를 지우고 sudo dpkg --configure -a 로 패키지 설정 문제를 고쳤다.
dpkg -l | grep -v ^ii 로 남은 망가진 패키지를 찾아 sudo apt-get remove --purge <package_name> 으로 하나씩 지웠다.
sudo apt-get install -f 로 빠진 의존성을 채우고 sudo apt-get install --reinstall linux-headers-$(uname -r) 로 커널 헤더를 다시 설치했다.
머신을 재부팅해 커널 패닉이 사라진 것을 확인했다.

후속 조치

GPU 드라이버 설치가 완전히 성공했는지 확인하고, 오류가 나면 바로 변경을 되돌린다.
단일 장애 지점을 없애도록 클러스터를 고가용성 구성으로 옮긴다.
고가용성 구성에서 Kube-API 를 로드 밸런서 뒤에 둔다.
장애를 기록하고 해결 과정을 추적할 티켓 시스템을 만든다.
미리 정해 둔 문제 해결 절차를 만들어 홈랩 장애 대응 시간을 줄인다.
Prometheus 와 Grafana 같은 인프라 모니터링을 넣어 문제를 미리 잡는다.
주요 서비스에 HTTP, TCP 검사를 거는 블랙박스 모니터링을 넣어 쿠버네티스 클러스터 밖에서도 장애를 잡는다.

교훈

드라이버 빌드 실패를 그대로 두면 몇 주 뒤 재부팅 때 터질 수 있다. 자동 알림이 없어서 발견과 복구가 늦었다. 마스터 노드가 하나뿐이라 노드 하나의 고장이 클러스터 전체 장애가 됐다. 원인을 찾은 뒤에는 비교적 간단히 고쳤고, 데이터 손실은 없었다.

출처

https://mustybatz.github.io/homelab/post-mortems/gpu-driver.html · blog

내 클러스터에도 있는지 확인하기

kubegap 은 Claude Code 나 Codex 에서 쿠버네티스 클러스터를 읽기만 하며 이 사례와 같은 상태를 점검합니다. 이 사례의 구성 요소: GPU 드라이버, 리눅스 커널, 쿠버네티스 API 서버. 점검 항목의 근거는 이 사례 같은 공개 보고서입니다.

kubegap 열기

AI 도구와 스크립트용

이 사례의 JSON: https://incidentlib-api.benchlet.com/cases/IL-0138
가장 비슷한 사례들: https://incidentlib-api.benchlet.com/cases/IL-0138/similar
MCP 서버(Streamable HTTP, 키 없음): https://incidentlib-mcp.benchlet.com/mcp

API 는 키가 필요 없습니다. MCP 서버는 search_incidents, get_incident, list_incidents, get_topic, vocab 도구를 내놓습니다. 사용법은 API 와 MCP.

증상

원인

감지

조치

후속 조치

교훈

출처

관련 사례

내 클러스터에도 있는지 확인하기

AI 도구와 스크립트용