[프로젝트 2]🔧 라즈베리파이 5에서 K3s 클러스터 올리기 – 하드웨어부터 Longhorn HA까지

클러스터 구축이 이렇게 험난할 줄은 몰랐습니다. 공식 문서대로 명령어를 따라 치면 금방 될 것 같았는데, 현실은 달랐어요. SSD가 시스템을 통째로 얼려버리고, 네트워크가 5분마다 끊기고, Worker 노드가 엉뚱한 IP로 붙고, Longhorn 매니저가 아예 뜨지를 않고. 이 포스팅은 그 삽질의 기록입니다.

🔗 K3s 위키 상세 문서: GitHub Wiki — Kubernetes(K3s) | Longhorn HA

---

🖥️ 하드웨어 구성

본격적인 이야기에 앞서 물리 환경을 간단히 소개하면, 노드 세 대는 이렇게 구성되어 있습니다.

노드	역할	RAM	저장소	네트워크
Master	Control Plane 전용	4GB	SSD 128GB	이더넷(eth0)
Worker 1	백업 감시 노드	8GB	SSD 256GB	이더넷(eth0)
Worker 2	메인 AI 감지 노드	8GB	SSD 256GB	이더넷(eth0)

모든 노드는 폐쇄망(이더넷)과 인터넷(Wi-Fi) 두 개의 네트워크 인터페이스를 동시에 사용합니다. 클러스터 내부 통신은 이더넷, 패키지 다운로드와 Docker Hub 이미지 pull은 Wi-Fi로 분리하는 구조입니다. 이 이중 네트워크 구조가 뒤에서 엄청난 트러블슈팅의 원인이 됩니다.

---

💥 Episode 1. SSD가 시스템을 얼려버렸다 — USB-SATA UAS 호환성 문제

첫 번째 시련은 하드웨어에서 왔습니다. 라즈베리파이 5를 SSD에 연결하고 부팅하면 처음에는 멀쩡하게 동작합니다. SSH도 잘 붙고, ping도 잘 가고. 그런데 VS Code Remote-SSH로 연결하거나 시간이 조금 지나면 시스템이 통째로 굳어버립니다.

증상:

• SSH가 먹통이 되고, 외부에서 ping을 보내면 Destination host unreachable
• 커널 패닉 로그는 없는데 쿨링 팬이 고속으로 돌면서 발열이 심해짐
• htop으로 확인하면 특정 CPU 코어 하나가 100%로 치솟는 Interrupt Storm 발생

원인은 USB-SATA 어댑터였습니다. 리눅스는 USB 연결 스토리지에 UAS(USB Attached SCSI) 프로토콜을 사용합니다. 병렬 처리로 빠른 성능을 내는 프로토콜인데, 저가형 어댑터 칩셋(JMicron 계열)이 이 드라이버와 충돌합니다. VS Code 인덱싱처럼 랜덤 I/O 부하가 걸리는 순간 컨트롤러가 데드락에 빠지면서 CPU가 인터럽트 폭풍에 시달리다가 시스템 전체가 응답 불능이 되는 것이었습니다.

해결: 커널 부팅 파라미터에 quirks를 추가해서 UAS를 끄고 BOT(Bulk-Only Transport) 모드로 강제 전환합니다.

# /boot/firmware/cmdline.txt 맨 앞이나 뒤에 추가
# 본인 어댑터 ID는 lsusb로 확인
usb-storage.quirks=7825:a2a4:u

모드	특징
BOT	1차선 도로 — 순차 처리, 느리지만 안정적
UAS	다차선 고속도로 — 병렬 처리, 빠르지만 칩셋 지원 필수

💡 교훈: USB-SATA 어댑터는 단순 케이블이 아닙니다. 칩셋 호환성을 타는 하나의 ‘장비’입니다. Longhorn처럼 스토리지 성능이 중요한 프로젝트라면 ASMedia ASM1153E 칩셋이 탑재된 어댑터를 권장합니다.

---

💥 Episode 2. 네트워크가 5분마다 끊겼다 — DHCP 타임아웃의 함정

SSD 문제를 해결하고 K3s 설치를 시작했습니다. 그런데 이번엔 이상한 일이 생겼어요. 부팅 직후에는 SSH가 잘 되는데, 5분 후에 정확하게 네트워크가 끊깁니다. 시스템이 다운된 건 아닙니다. 전원 버튼을 누르면 정상 종료 프로세스가 돌거든요. 네트워크만 딱 죽는 거예요.

원인을 찾는 데 꽤 오래 걸렸습니다. K3s CNI 충돌? Longhorn I/O 병목? 메모리 스래싱? 온갖 복잡한 가설을 세웠는데, 정답은 정말 허무했습니다.

이더넷에 고정 IP를 입력했지만 할당 방식을 ‘자동(Automatic)’으로 놔뒀던 것입니다.

폐쇄망 허브에는 DHCP 서버가 없으니, NetworkManager가 5분 동안 DHCP 응답을 기다리다가 타임아웃 처리 후 이더넷 인터페이스를 스스로 꺼버립니다. 300초, 딱 5분입니다.

# 해결: nmtui로 IPv4 할당 방식을 수동으로 변경
sudo nmtui
# IPv4 CONFIGURATION: <Automatic> → <Manual> 로 변경

이 외에도 이 과정에서 잠재적 위험 요인들을 추가로 발견하고 조치했습니다.

# K3s가 Wi-Fi가 아닌 이더넷으로만 통신하도록 강제
# /etc/systemd/system/k3s.service 실행 옵션에 추가
--flannel-iface=eth0

💡 교훈: 폐쇄망 + 외부망이 공존하는 환경에서는 ① 폐쇄망 인터페이스의 게이트웨이를 비우고, ② IPv4를 완전한 수동(Manual)으로 설정하고, ③ 애플리케이션에 사용할 인터페이스를 명확히 지정해야 합니다.

---

💥 Episode 3. Worker 노드가 엉뚱한 IP로 붙었다 – 토큰 잘림과 재설치

Worker 노드를 클러스터에 조인할 차례입니다. kubectl get nodes -o wide로 확인해보니 Worker 노드들의 INTERNAL-IP가 의도했던 192.168.0.x가 아닌 엉뚱한 192.168.219.x 대역으로 표시됩니다.

IP를 강제하기 위해 k3s-agent.service 설정 파일을 직접 nano 에디터로 수정했는데, 서비스를 재시작하니 프로세스가 아예 멈추고 반환이 안 됩니다.

원인은 두 가지였습니다. 첫째, 다중 네트워크 환경에서 K3s가 의도치 않은 인터페이스를 기본 통신 IP로 잡았습니다. 둘째, nano로 긴 K3s 토큰을 복붙하는 과정에서 토큰 끝이 잘려나갔습니다. 불완전한 인증 정보로 마스터와 계속 연결을 시도하며 프로세스가 멈춰버린 것이었습니다.

해결은 직접 수정이 아니라 공식 스크립트로 깔끔하게 재설치하는 것이었습니다.

# 마스터 노드에서 온전한 토큰 다시 확인
cat /var/lib/rancher/k3s/server/node-token

# Worker 노드에서 공식 스크립트로 재설치 + IP 강제 주입
curl -sfL https://get.k3s.io | \
  K3S_URL=https://192.168.0.10:6443 \
  K3S_TOKEN="<온전한_토큰>" \
  INSTALL_K3S_EXEC="--node-ip=192.168.0.11" \
  sh -

💡 교훈: K3s 설정을 변경할 때는 서비스 파일을 직접 수정하는 것보다 공식 설치 스크립트에 환경변수를 넘겨 재실행하는 것이 오타·텍스트 잘림 같은 휴먼 에러를 방지하는 가장 안전한 방법입니다. 재설치해도 기존 파드 데이터는 날아가지 않습니다.

---

💥 Episode 4. Longhorn 3-Node HA – “닭과 알의 문제”

드디어 Longhorn을 설치할 차례입니다. Master 노드(RAM 4GB)를 AI 파드 같은 무거운 연산으로부터 보호하면서, 남는 디스크 자원은 Longhorn 3-Node HA 스토리지로 활용하는 것이 목표였습니다.

Master 노드에 NoSchedule Taint(자물쇠)를 걸고, Longhorn 시스템에만 Toleration(만능 열쇠)을 부여하려 했습니다. 그런데 Longhorn 대시보드에서 Master 노드가 계속 READY: False 상태입니다.

kubectl describe node master
# → "manager pod missing: node master has no manager pod running on it"

원인은 “닭과 알의 문제”였습니다.

Longhorn 전역 설정에 Toleration을 패치하면 csi-attacher, csi-provisioner 같은 자잘한 컴포넌트들은 열쇠를 받고 Master 노드에 잘 들어옵니다. 하지만 정작 이 열쇠들을 발급하고 관리해야 할 longhorn-manager 데몬셋 자신에게는 Toleration이 누락되어 있어서, 매니저 파드 자체가 Master 노드에 생성되지 못하는 상황이었습니다.

해결: Longhorn Manager 데몬셋에 직접 Toleration을 강제 주입합니다.

# 1단계: 꼬인 Longhorn 깔끔하게 재설치
# (공식 Uninstall Job으로 찌꺼기 완전 제거 후 재설치)

# 2단계: longhorn-manager 데몬셋에 직접 패치
kubectl patch ds longhorn-manager -n longhorn-system -p \
  '{"spec":{"template":{"spec":{"tolerations":[{
    "key":"node-role.kubernetes.io/master",
    "operator":"Equal",
    "value":"true",
    "effect":"NoSchedule"
  }]}}}}'

패치 실행 후 단 6초 만에 Master 노드에 longhorn-manager 파드가 1/1 Running 상태로 생성됐습니다. 세 대 노드 모두 READY: True로 바뀌면서 완벽한 3-Node HA 분산 스토리지 구성을 달성했습니다.

📸 이미지 자리: Longhorn 대시보드 — 3-Node READY:True 상태 확인 화면

---

✅ 여기까지의 성과

Episode 1~4를 거치며 이렇게 됐습니다.

항목	상태
라즈베리파이 3대 SSD 부팅 안정화	✅
폐쇄망 이더넷 고정 IP 설정	✅
K3s 3-Node 클러스터 조인 완료	✅
Longhorn 3-Node HA 분산 스토리지 구성	✅
Master 노드 Control Plane 격리 (Taint)	✅

하지만 진짜 고난은 다음 편에서 시작됩니다. 사내망 DHCP가 클러스터 노드와 IP 충돌을 일으키면서 MetalLB 설치가 클러스터 전체를 무너뜨리는 사건이 기다리고 있었거든요.

🔗 다음 편: 3편 — 사내망 DHCP 충돌과 K3s 전면 재구축 + GitOps 파이프라인 완성 🔗 전체 트러블슈팅 로그: GitHub Wiki — Troubleshooting & Operations Log