[cloud ‐ TroubleShooting] Kubernetes Master Node Kubelet 장애 - 100-hours-a-week/5-yeosa-wiki GitHub Wiki

문제 요약 (Issue Summary)

문제 발생 일시: 2025-04-26 14:56
문제 발생 위치: Kubernetes Master Node
문제 증상: kubectl 명령어 사용 시 API 서버 연결 실패

현상 (Observed Symptoms)

kubectl get pods -A 명령어 입력 시

- `connection refused` 에러 발생
- `The connection to the server 192.168.100.3:6443 was refused` 메시지 출력

kubelet 서비스가 비정상 상태 (auto-restart 반복)
Kubernetes Control Plane 컴포넌트 미동작

기대 결과 (Expected Behavior)

kubelet 서비스가 정상적으로 기동되어야 함
Kubernetes API 서버(6443 포트)가 정상적으로 열려야 함
kubectl get nodes 명령어로 노드 상태를 조회할 수 있어야 함

시도한 해결 방법 (What I Tried)

containerd 서비스 상태 확인
- 정상 동작 중
kubelet 서비스 재시작
- containerd 기동 후에도 kubelet 재기동 실패
kubelet 에러 로그 확인
- sudo journalctl -u kubelet --no-pager | tail -n 50
- "failed to run Kubelet: running with swap on is not supported" 에러 확인
Swap 비활성화
- /etc/fstab 파일 수정하여 /swap.img 항목을 주석 처리해 영구 비활성화 설정

kubelet 재시작
- swap 해제 이후 sudo systemctl restart kubelet 명령어로 정상 기동 확인

관련 로그 / 명령어 결과 (Logs / Outputs)

bash
복사편집
# kubelet 에러 로그
failed to run Kubelet: running with swap on is not supported, please disable swap! or set --fail-swap-on flag to false.

/proc/swaps contained:
/swap.img  file  2977788  0  -2

# fstab 파일 수정 전
/swap.img       none    swap    sw      0       0

# 수정 후
#/swap.img       none    swap    sw      0       0

# swapoff 후 상태
sudo systemctl status kubelet
→ Active: active (running)

# kubectl 명령 정상 작동
kubectl get nodes
→ master 노드 Ready 상태

원인 분석 (Root Cause Analysis)

Kubernetes는 기본적으로 swap 메모리가 활성화되어 있는 환경에서 kubelet이 기동하지 않도록 설계됨
마스터 노드 서버에 /swap.img 파일을 통한 swap이 활성화되어 있었음
이로 인해 kubelet이 swap 사용 불가 정책에 걸려 지속적으로 실패(exit 1) 및 재시도(auto-restart) 상태가 됨
결과적으로 kube-apiserver가 기동되지 않아 kubectl 명령어가 실패

해결 방법 (Resolution Plan)

/etc/fstab 파일 수정하여 swap 영역 주석 처리
sudo swapoff -a 명령어로 swap 메모리 일시 해제
sudo systemctl restart kubelet 명령어로 kubelet 서비스 재기동
kubectl get nodes 명령어를 통해 정상 동작 확인
Master Node, Worker Node 둘 다 적용해야함