Kubernetes 환경에서 애플리케이션이 제대로 작동하지 않을 때, 실시간으로 Pod 내부 상태를 살펴보며 원인을 파악하는 것은 매우 중요합니다. 하지만 일반적인 방법으로는 이미 실행 중인 컨테이너에 도구를 추가하거나 직접 접속해서 조사하는 것이 쉽지 않습니다. 이럴 때 사용할 수 있는 것이 바로 kubectl debug입니다.
이 글에서는 kubectl debug를 사용하여 Pod와 Node를 디버깅하는 방법에 대해 알아보겠습니다.
kubectl debug는 Kubernetes에서 디버깅 목적의 임시 컨테이너(Ephemeral Container)를 기존 Pod에 주입할 수 있게 해주는 강력한 CLI 도구입니다.
기존 컨테이너를 멈추거나 수정하지 않고도, Pod 내부 상태를 실시간으로 들여다볼 수 있습니다.
kubectl debug는 Kubernetes 1.18부터 도입되었으며, Ephemeral Container는 1.23부터 GA(Stable) 기능입니다.
1. 임시 컨테이너
다음과 같이 Kubernetes에서 실행 중인 Pod에 디버깅을 위해 busybox를 사용하여 임시 컨테이너를 추가합니다.
kubectl debug -n my-namespace -it \
my-app-pod \
--image=busybox \
--target=my-container \
-- /bin/bash
이렇게 하면 기존 컨테이너와 임시 컨테이너가 네트워크, PID, IPC 네임스페이스를 공유합니다.
busybox 이미지로 생성된 컨테이너의 쉘에서 Pod 내부의 상황을 실시간으로 확인할 수 있습니다.
기존 컨테이너의 파일시스템은 /proc/<기존_컨테이너_프로세스_ID>/root 경로에서 확인할 수 있습니다.
주요 옵션
- –image: 디버그 컨테이너 이미지 지정
- –target: 네트워크/네임스페이스 공유할 대상 컨테이너 지정 (단일 컨테이너는 생략 가능)
- –copy-to: 기존 Pod 복사 후 새로 생성되는 Pod 이름
- -it: 인터랙티브 모드 (터미널 접속)
- – : 디버깅 컨테이너에서 실행할 명령
참고로 임시 컨테이너 제거를 위해서는 kubectl 명령어를 사용하여 Pod를 삭제하여 다시 만들어야 합니다.
2. 네트워크 트래픽 분석
Nginx 배포하고 tcpdump를 사용하여 Pod의 네트워크 트래픽을 실시간으로 캡처해보겠습니다.
Nginx 배포
kubectl create deploy nginx --image=nginx
kubectl expose deployment nginx --type=LoadBalancer --name=nginx-service --port=80 --target-port=80
Pod 확인
kubectl get pods
nginx-bf5d5cf98-r9lbz 1/1 Running 0 10s
tcpdump 컨테이너 추가
kubectl debug -n default -it \
nginx-bf5d5cf98-r9lbz \
--image=nicolaka/netshoot \
--target=nginx \
--share-processes \
-- tcpdump -i eth0 port 80 -A
console에서 tcpdump를 출력하는 대신
tcpdump -i eth0 port 80 -w /tmp/capture.pcap로 변경하면
.pcap 파일을 kubectl cp로 복사해 Wireshark에서 분석할 수도 있습니다.
HTTP 요청 실행
kubectl run curl --rm -it --image=busybox --restart=Never -- /bin/sh
wget --header="Authorization: Bearer <YOUR_ACCESS_TOKEN>" -O- http://nginx.default.svc.cluster.local
HTTP 요청 실행을 하면, tcpdump를 실행하고 있는 터미널 창에서 HTTP 요청/응답 패킷이 실시간으로 보입니다.
3. 네트워크 진단 도구
praqma/network-multitool은 curl, dig, ping, netcat, route 등 다양한 네트워크 진단 도구가 사전 설치된 올인원 이미지입니다.
단순 쉘 접속뿐만 아니라 다양한 네트워크 관련 진단을 한 번에 실행할 수 있어 유용합니다.
네트워크 진단 컨테이너 추가
kubectl debug -n default -it \
nginx-bf5d5cf98-jxq4m \
--image=wbitt/network-multitool \
--target=nginx \
-- /bin/bash
네트워크 진단
# DNS 조회
dig nginx.default.svc.cluster.local
# HTTP 요청
curl -v http://nginx.default.svc.cluster.local
# 포트 스캔
nc -zv nginx.default.svc.cluster.local 80
4. Pod 복사
–copy-to 옵션을 사용하여 기존 Pod를 건드리지 않고 복사본을 만들어 디버깅할 수 있습니다.
kubectl debug -n security orchestrator-69677785bf-4p2j8 \
--copy-to=debug-orchestrator \
--container=debugger \
--image=wbitt/network-multitool \
-- sleep infinity
kubectl -n security exec -it debug-orchestrator -c debugger -- /bin/bash
기존 Pod가 Crashbackoff 상태라면 이 Pod의 복사본에서도 똑같이 이 문제가 발생합니다. 이런 경우, 이미지를 변경해 복사 Pod를 생성하고 같은 조건에서 기능이 동작하는지 확인할 수 있습니다.
kubectl debug -n security orchestrator-69677785bf-4p2j8 \
--copy-to=debug-orchestrator --set-image=*=orchestrator:988c327
debugger 컨테이너에서 복제된 Pod의 PVC, ConfigMap, Secret 등 설정 등을 확인하기 위해서는, 복제된 Pod의 Manifest를 수정하여 볼륨 마운트 설정을 추가하고 재배포를 해야합니다. 또한 기존 Pod 설정에 문제가 있는 경우, 이 과정에서 Manifest를 수정해 재배포함으로써 문제를 재현하거나 원인을 분석할 수도 있습니다.
5. Node 디버깅
Kubernetes에서 Node를 디버깅할 때, kubectl debug 명령에 미리 정의된 프로파일을 적용하면, 필요한 특정 권한과 보안 수준을 간편하게 설정할 수 있습니다.
프로파일
- legacy : Kubernetes 1.22와 하위 호환되는 속성
- general : 일반 디버깅에 적합한 기본 속성
- baseline : PodSecurityStandard의 baseline 정책 호환 속성
- restricted : PodSecurityStandard의 restricted 정책 호환 속성
- netadmin : 네트워크 관리자 권한 포함한 속성
- sysadmin : 시스템 관리자(root) 권한 포함한 속성
다음과 같이 특정 노드에 디버그깅을 위한 Pod를 생성하고 sysadmin 프로파일을 적용하여, /proc/$$/status에서 프로세스의 Capabilities 상태를 확인해보겠습니다.
kubectl debug -it node/k8s-worker-01 --image=busybox --target=myapp --profile=sysadmin
/ # grep Cap /proc/$$/status
CapInh: 0000000000000000
CapPrm: 000001ffffffffff
CapEff: 000001ffffffffff
CapBnd: 000001ffffffffff
CapAmb: 0000000000000000
6. 마무리
kubectl debug는 Kubernetes 환경에서 운영 중인 서비스를 멈추지 않고 문제를 진단할 수 있는 필수 디버깅 도구입니다.
특히 netshoot와 network-multitool 같은 다목적 이미지를 활용하면, SRE/DevOps 환경에서 네트워크 및 애플리케이션 문제를 신속하게 분석할 수 있습니다.
참고 링크