🕵️‍♂️ 내 컨테이너에 무슨 일이? 쿠버네티스 로깅 & 디버깅 삼대장 완전 정복!

안녕하세요, 쿠버네티스 항해를 떠나는 모든 개발자, 엔지니어 여러분! 🚀 애플리케이션을 컨테이너에 담아 쿠버네티스라는 거대한 바다에 띄웠지만, 가끔은 예상치 못한 암초를 만나거나 엔진(애플리케이션)이 이상한 소리를 낼 때가 있죠. 컨테이너 내부는 직접 들여다보기 힘든 블랙박스와 같아서 문제가 생기면 막막하게 느껴질 수 있습니다.

 

하지만 걱정 마세요! 쿠버네티스는 우리에게 컨테이너 내부를 훤히 들여다볼 수 있는 강력한 잠망경과 원격 조종 도구를 제공합니다. 오늘은 그중에서도 가장 핵심적인 로깅 및 디버깅 삼대장, kubectl logs, exec, debug 사용법을 아주 상세하게 파헤쳐 보겠습니다!

 

---

1. kubectl logs: 컨테이너의 블랙박스를 열어라 📜

가장 기본적이면서도 가장 중요한 명령어입니다. kubectl logs는 컨테이너가 표준 출력(stdout)과 표준 에러(stderr)로 내보낸 모든 기록, 즉 로그를 확인하는 데 사용됩니다. 애플리케이션이 왜 비정상 종료되었는지, 어떤 에러 메시지를 출력했는지 확인하는 첫 번째 단계는 바로 로그를 보는 것입니다.

• 역할: 컨테이너의 과거 및 실시간 로그를 확인합니다.
• 핵심 사용법:
  • 기본 로그 확인:만약 파드에 컨테이너가 여러 개 있다면, 어떤 컨테이너의 로그를 볼지 지정해야 합니다 (-c 플래그).

    kubectl logs <pod-name> -c <container-name>
    

    kubectl logs <pod-name>
    

     

  • 실시간 로그 스트리밍 (따라가기): -f 또는 --follow 플래그를 사용하면 로그가 생성될 때마다 실시간으로 터미널에 출력됩니다. 개발 중 실시간으로 에러를 확인할 때 필수적이죠!

    kubectl logs -f <pod-name> -c <container-name>
    

  • 이전 컨테이너 로그 확인: 컨테이너가 비정상적으로 종료되고 재시작되었다면, 현재 컨테이너의 로그에는 아무것도 없을 수 있습니다. 이때 -p 또는 --previous 플래그를 사용하면 직전에 죽었던 컨테이너의 로그를 확인할 수 있습니다. 문제 해결의 결정적 단서가 될 때가 많습니다.

    kubectl logs -p <pod-name> -c <container-name>
    

• 비유: kubectl logs는 비행기 사고의 원인을 밝혀내는 '블랙박스' 📦와 같습니다. 컨테이너가 추락(Crash)했을 때, 그 안에 담긴 마지막 기록을 통해 원인을 파악하는 것이죠.

---

2. kubectl exec: 컨테이너 안으로 순간이동! 🦸

로그만으로는 부족할 때가 있습니다. "컨테이너 안의 파일 시스템은 어떻게 생겼지?", "지금 어떤 프로세스가 돌고 있지?", "여기서 다른 서버로 네트워크는 연결되나?" 같은 궁금증이 생길 때, kubectl exec는 우리를 실행 중인 컨테이너 안으로 직접 들여보내줍니다.

• 역할: 실행 중인 컨테이너 내부에서 원하는 명령어를 실행합니다.
• 핵심 사용법:
  • 컨테이너에 셸(shell) 접속: 가장 일반적인 사용법입니다. -it 플래그를 사용하여 상호작용이 가능한 터미널 세션을 엽니다.이제 여러분은 컨테이너 안입니다! ls -al, ps aux, cat /etc/hosts 등 리눅스 명령어로 내부를 마음껏 탐색할 수 있습니다.

    # /bin/bash 셸이 있는 컨테이너의 경우
    kubectl exec -it <pod-name> -- /bin/bash
    
    # /bin/sh 셸만 있는 컨테이너의 경우
    kubectl exec -it <pod-name> -- /bin/sh
    

  • 단일 명령어 실행: 컨테이너에 접속하지 않고 특정 명령어만 실행하고 싶을 때 사용합니다.

    kubectl exec <pod-name> -- cat /app/config.yaml
    

• 비유: kubectl exec는 개발자를 위한 '순간이동 장치' ✨입니다. 문제가 발생한 현장(컨테이너)으로 즉시 이동하여 직접 상황을 조사하고 문제를 해결할 수 있게 해줍니다.

---

3. kubectl debug: 최첨단 진단 드론 투입! 🚁

최신 쿠버네티스 환경에서는 보안과 효율을 위해 셸이나 기본적인 디버깅 도구조차 없는 최소한의 이미지('distroless' 이미지)를 사용하는 경우가 많아지고 있습니다. 이런 컨테이너에는 kubectl exec로 접속할 셸이 없어서 디버깅이 막막했죠. 이때 등장한 해결사가 바로 kubectl debug (v1.18+ 정식 기능) 입니다.

• 역할: 원본 컨테이너를 변경하지 않고 디버깅을 위한 임시 컨테이너를 생성하고 연결합니다.
• 핵심 사용법:
  • 실행 중인 파드에 디버깅 컨테이너 추가: 가장 강력한 기능입니다. 실행 중인 파드에 busybox나 ubuntu처럼 디버깅 도구가 풍부한 컨테이너를 '주입'합니다. 이 임시 컨테이너는 원래 컨테이너와 네트워크, 프로세스 공간을 공유할 수 있어 localhost로 통신하거나 다른 프로세스를 들여다볼 수 있습니다.

    # 'my-pod'에 busybox 이미지를 사용한 임시 컨테이너를 붙여서 디버깅
    kubectl debug -it my-pod --image=busybox --target=my-app-container
    

  • 파드 복사본으로 디버깅: CrashLoopBackOff 상태처럼 파드가 계속 재시작되어 exec나 logs를 보기 힘들 때, 해당 파드의 복사본을 만들어 디버깅 세션을 시작할 수 있습니다. 이때 컨테이너의 시작 명령(command)을 변경하여 파드가 바로 종료되지 않게 할 수 있습니다.

    kubectl debug my-pod -it --copy-to=my-pod-debug --container=my-app -- sh
    

• 비유: kubectl debug는 '최첨단 진단 드론' 과 같습니다. 원본 기계(컨테이너)를 멈추거나 분해하지 않고도, 정밀한 도구를 갖춘 소형 드론(임시 컨테이너)을 내부에 투입하여 문제를 실시간으로 진단하고 분석하는 것이죠.

---

🎉 결론: 디버깅 삼대장으로 쿠버네티스 마스터하기

kubectl logs, exec, debug는 쿠버네티스 환경에서 발생하는 거의 모든 문제를 해결하는 데 필요한 필수 도구입니다.

• 1단계: logs로 현상 파악하기
• 2단계: exec로 내부 진입하여 심층 분석하기
• 3단계: debug로 셸 없는 환경이나 까다로운 문제 해결하기

이 세 가지 명령어만 손에 익숙해진다면, 아무리 복잡한 컨테이너 문제라도 자신감을 갖고 해결할 수 있을 겁니다. 이제 여러분의 컨테이너에 무슨 일이 생겨도 당황하지 마세요!

 

 

Tags: 쿠버네티스, Kubernetes, kubectl, 디버깅, 로깅, DevOps, 컨테이너, 문제 해결, logs, exec, debug