[오픈소스] 쿠버네티스 pod crash 원인을 AI가 자동으로 분석해주는 도구 만들었습니다
안녕하세요! OKKY 회원 여러분. 백엔드/DevOps 개발을 하다 보면 쿠버네티스 때문에 퇴근이 늦어지는 날이 참 많은 것 같습니다.
파드는 CrashLoopBackOff 상태로 계속 재시작되는데, kubectl logs를 쳐보면 수천 줄의 로그가 쏟아져서 어디부터 봐야 할지 모르겠고... describe 명령어를 쳐봐도 "Back-off restarting failed container"라는 뻔한 메시지만 나올 때의 그 답답함, 다들 한 번쯤 겪어보셨을 거라 생각합니다.
저 역시 2시간 동안 구글링하며 헤매다가 알고 보니 단순한 메모리(OOM) 설정 문제였다는 걸 깨닫고 허탈해했던 경험이 참 많았습니다.
"매번 반복되는 이 삽질을 AI가 대신 분석해 줄 수는 없을까?"
이런 고민 끝에 [K8s Doctor MCP] 라는 도구를 만들게 되어 공유드립니다.
🩺 K8s Doctor MCP가 뭔가요?
요즘 핫한 Model Context Protocol (MCP) 을 기반으로, 쿠버네티스 파드의 장애 원인을 AI(Claude)가 자동으로 분석하고 해결책까지 제안해주는 디버깅 도구입니다.
단순히 로그를 보여주는 게 아니라, AI가 수천 줄의 로그 속에서 "진짜 문제"를 찾아내어 사람이 이해하기 쉬운 말로 설명해 줍니다.
👀 무엇이 달라지나요?
[기존의 우리 모습]
$ kubectl get pods
NAME STATUS RESTARTS
api-server CrashLoopBackOff 15
$ kubectl logs api-server
... (로그 5000줄 출력됨) ...
(아... 도대체 어디가 문제야? 😫)[K8s Doctor와 함께]
나: "api-server 파드가 자꾸 죽는데 이유가 뭐야?"
K8s Doctor: 🔍 CrashLoopBackOff 진단 결과
Exit Code: 137 (OOM Killed)
근본 원인: 컨테이너가 설정된 메모리 제한을 초과했습니다.
로그 발견 (1234번째 줄):
FATAL ERROR: Reached heap limit Allocation failed💡 해결 제안:
resources.limits.memory를 현재 512Mi에서 768Mi 이상으로 증설하는 것을 권장합니다.
🛠 주요 기능
종합 진단 (
diagnose-pod): 파드의 상태, 이벤트, 리소스, 로그를 한 번에 스캔하여 건강도 점수와 함께 보여줍니다.CrashLoop 해결사 (
debug-crashloop): 137(OOM), 143(SIGTERM) 등 종료 코드를 해석하고, 이전 컨테이너 로그까지 뒤져서 원인을 찾습니다.스마트 로그 분석 (
analyze-logs): "DB 연결 실패", "DNS 에러" 같은 핵심 키워드만 쏙쏙 뽑아서 정리해 줍니다.보안 및 리소스 체크: 메모리가 90% 이상 차오르면 경고를 주고, 기본적인 보안 설정 실수도 잡아냅니다.
💻 설치 및 사용 방법
Node.js(18 이상)와 kubectl이 설정된 환경이라면 어디서든 사용 가능합니다. (minikube, EKS, GKE, Kind 등)
1. npm으로 설치
npm install -g @zerry_jin/k8s-doctor-mcp2. Claude Code에 등록
claude mcp add k8s-doctor -- k8s-doctor-mcp(Claude Desktop App을 쓰시는 분들은 설정 파일에 추가하여 사용 가능합니다.)
🔒 보안은 걱정하지 마세요
제 자신이 현업에서 쓰려고 만든 만큼 보안을 최우선으로 고려했습니다.
Read-Only: 클러스터 상태를 변경(Write)하지 않고 오직 조회(get, list, logs) 권한만 사용합니다.
로컬 실행:
kubeconfig는 사용자 PC 내에서만 사용되며, 수집된 로그나 데이터가 외부 서버로 전송되지 않습니다.
💭 왜 만들었나요?
DevOps 엔지니어로 일하면서 수백 건의 장애를 처리하다 보니, 장애의 90%는 OOM, DB 연결 오류, 설정 파일 누락 같은 반복적인 패턴이더라고요. 매번 같은 에러 로그를 복사해서 구글링하는 시간이 너무 아깝게 느껴졌습니다.
여러분의 퇴근 시간이 조금이라도 빨라지는 데 이 도구가 도움이 되었으면 좋겠습니다.
🔗 링크 및 피드백
부족한 점이 많겠지만, 써보시고 피드백 주시면 감사한 마음으로 개선해 나가겠습니다. 깃허브 Star ⭐ 하나 눌러주시면 개발자에게 정말 큰 힘이 됩니다! 😊
긴 글 읽어주셔서 감사합니다. 오늘도 평온한 클러스터 되세요! 🚢⚓️
