쿠버네티스 트러블슈팅 모음

온프레미스 클러스터를 운영하며 실제로 만난 오류들을 주제별로 정리했습니다. 같은 증상을 만났을 때 빠르게 찾아 쓰라고 모아둔 노트예요.

접속 · 인증서

The connection to the server was refused 또는 x509: certificate signed by unknown authority

kubeconfig의 인증서나 파일에 문제가 생겨 클러스터에 접근이 안 되는 경우입니다.

rm ~/.kube/config
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
# 또는
systemctl daemon-reload && systemctl restart kubelet

use of closed network connection (인증서 갱신 중)

갱신 도중 실행 중이던 apiserver·controller-manager가 예전 인증서를 들고 있어 발생합니다. systemctl restart kubelet 등 재로딩을 마치면 정리됩니다.

CNI · 네트워크

cni0 already has an IP address different from ...

CNI 상태가 꼬여 파드 생성이 안 되는 상황입니다. 클러스터를 초기화하는 게 확실합니다.

kubeadm reset
systemctl stop kubelet
rm -rf /var/lib/cni/ /var/lib/kubelet/* /etc/cni/
ip link delete cni0
ip link delete flannel.1
# 재부팅 후 재구성

노드 · 자원

node(s) had untolerated taint {node.kubernetes.io/disk-pressure}

디스크 공간 부족입니다. VMware 기준으로 무중단 증설 흐름은 이렇습니다.

# 1) 문제 워커에 taint를 걸고 파드를 다른 노드로 이동
kubectl taint node k8sworker1 key1=value1:NoSchedule

# 2) 워커 종료 후 VMware에서 디스크 Expand (스냅샷 있으면 불가)
# 3) 파티션/파일시스템 확장
parted /dev/sda            # resizepart 로 최대 용량까지
resize2fs /dev/sda1
df -h                       # 확인

# 4) taint 해제
kubectl taint node k8sworker1 key1=value1:NoSchedule-

Evicted 상태의 파드

자원 부족·노드 장애·드레인 등으로 파드가 강제 퇴출된 상태입니다. 새 파드가 정상 동작 중이라면 Evicted 파드는 지워도 됩니다.

kubectl get pods --field-selector=status.phase=Failed -n <ns> \
  | grep Evicted | awk '{print $1}' | xargs kubectl delete pod -n <ns>

단, 컨트롤러 없이 수동 생성한 파드는 삭제 후 자동 복구되지 않으니 주의하세요.

ContainerStatus from runtime service failed ... NotFound

워커에 컨테이너 런타임이 제대로 안 깔린 경우입니다. 모든 워커에 런타임(containerd)이 정상 설치·구동 중인지 확인합니다.

스토리지 · NFS

you might need a /sbin/mount.<type> helper program

NFS 마운트 헬퍼가 없어서 나는 오류입니다. 모든 노드에 클라이언트 패키지를 설치합니다.

apt-get install -y nfs-common

재부팅 후 NFS가 이상하고 PVC가 안 붙을 때

VMware 재부팅 과정에서 /dev/sda 와 /dev/sdb 순서가 바뀌어 /etc/fstab 의 마운트가 엉키는 경우가 있습니다. 다시 마운트한 뒤 PVC를 붙이면 Bound 됩니다. 근본 해결은 fstab을 장치명 대신 UUID로 지정하는 것입니다(다음 리눅스 편에서 다룹니다).

로그 · 모니터링

failed to create fsnotify watcher: too many open files

kubectl logs -f 중 감시 파일 한도를 넘겨 발생합니다. inotify 한도를 올립니다.

sysctl -w fs.inotify.max_user_instances=1280
sysctl -w fs.inotify.max_user_watches=81920
sysctl -w fs.inotify.max_queued_events=32768

Metrics Server가 노드 메트릭을 못 긁을 때 (cannot validate certificate ... doesn't contain any IP SANs)

kubelet 서빙 인증서 문제입니다. 모든 노드에 serverTLSBootstrap: true 를 넣고 kubelet 재시작 → 마스터에서 kubectl get csr 후 승인합니다. 워커 정보 수집이 안 되면 metrics-server Deployment에 hostNetwork: true 를 추가하면 해결되는 경우가 있습니다.

서비스 (MongoDB)

NotWritablePrimary (레플리카셋)

Node.js MongoDB 드라이버가 DNS 라운드로빈을 지원하지 않아 세컨더리에 쓰기를 시도하며 나는 오류입니다. 접속 URL에 모든 멤버를 명시하고 replicaSet 을 지정해 해결했습니다.

mongodb://mongodb-0.mongo-in,mongodb-1.mongo-in,mongodb-2.mongo-in:27017/admin?replicaSet=rs0&authSource=admin

---

장애 대응의 공통점은 결국 하나예요. describe, journalctl -xe, kubectl logs 로 원인부터 확인하기. 증상만 보고 손대기 시작하면 더 꼬입니다. 그리고 스토리지를 만질 때는 항상 백업이 먼저입니다.