kubectl debug의 --profile 옵션, 이거 모르는 분 꽤 많더라

kubectl debug는 다들 쓴다. Pod에 ephemeral container 붙여서 shell 뜨는 거. 그런데 어제 팀 후배가 "노드 debug 뜨는데 왜 iptables 명령이 안 먹혀요?" 하고 물어봤다. 답은 --profile 옵션이었다.

프로파일이 6개나 있다

--profile 은 기본값이 general인데, 사실 상황별로 6가지가 있다.

• legacy — 예전 기본값. 곧 deprecated 예정이라 안 쓰는 게 낫다
• general — 현재 기본값. Pod debug 시 SYS_PTRACE 붙여준다
• baseline — PodSecurityStandard baseline 정책과 호환
• restricted — baseline + non-root, capability 전부 drop
• netadmin — 네트워크 관리자 권한. iptables, tcpdump 같은 거 쓸 때
• sysadmin — root 권한 풀로 필요할 때

노드 디버깅한다고 kubectl debug node/xxx --image=busybox만 딱 치면 general이 붙는데, 여기서는 network namespace 조작이 제한적이라 tcpdump로 캡처하면 원하는 인터페이스가 안 보인다. 이럴 때 --profile=netadmin 붙이면 CAP_NET_ADMIN, CAP_NET_RAW 다 붙어서 자유롭게 된다.

# 네트워크 트러블슈팅 - 이게 실무에서 제일 자주 쓴다
kubectl debug node/ip-10-0-1-42 -it --image=nicolaka/netshoot --profile=netadmin

# 시스템 레벨 파일/프로세스 뒤질 때
kubectl debug node/ip-10-0-1-42 -it --image=ubuntu --profile=sysadmin

# PSA restricted 걸린 네임스페이스에서 Pod debug 붙일 때
kubectl debug pod/my-app -it --image=busybox --profile=restricted --target=my-app

특히 마지막 케이스가 은근 함정이다. PSA restricted 붙여둔 네임스페이스에서 general 프로파일로 debug 시도하면 admission이 거부한다. 왜 안 되는지 몰라서 한참 헤매기 쉬운데, 이때 --profile=restricted를 명시하면 된다.

커스텀 프로파일도 된다

1.31부터 --custom 플래그로 JSON 파일 넘겨서 컨테이너 spec을 직접 override할 수 있다. 특정 볼륨 마운트를 붙이거나, 특정 env를 넣거나 할 때 유용하다.

cat > debug-profile.json <<EOF
{
  "securityContext": {
    "capabilities": {
      "add": ["SYS_PTRACE", "NET_ADMIN"]
    }
  },
  "volumeMounts": [
    {"name": "host-proc", "mountPath": "/host/proc"}
  ]
}
EOF

kubectl debug node/xxx -it --image=busybox --custom=debug-profile.json

프로파일 이름으로 커버 안 되는 조합이 필요할 때만 쓴다. 대부분은 built-in 프로파일로 충분하다.

솔직히 나도 두어 달 전까지는 general 하나만 쓰고 있었다. 알아두면 편해요.

---

태그: kubernetes, kubectl, debug, DevOps, 트러블슈팅

참고:

 

• Kubernetes 1.31 custom profiling kubectl debug

 

• kubectl debug netadmin profile 사용기