kubectl debug în Kubernetes (kubectl)

kubectl debug (POD | node/NOD) -it --image=IMAGINE [--target=CONTAINER] [--copy-to=POD_NOU]

Ce face kubectl debug

Imaginile moderne de producție (distroless, scratch, imagini minime fără root) nu conțin sh, curl, dig sau tcpdump, așa că kubectl exec nu te poate ajuta. Comanda kubectl debug rezolvă problema prin trei moduri de lucru:

1) Container efemer atașat unui pod care rulează: adaugă din mers un container cu unelte (de exemplu busybox sau nicolaka/netshoot) care împarte rețeaua și, cu --target, chiar și spațiul de procese și sistemul de fișiere (prin /proc/1/root) cu containerul aplicației.

2) Copie a pod-ului cu --copy-to: când pod-ul original crăpă imediat la pornire, creezi o clonă căreia îi schimbi comanda în sleep 1h sau îi schimbi imaginea. 3) Depanare de nod cu kubectl debug node/NUME: pornește un pod pe nodul respectiv cu filesystemul gazdei montat în /host.

Opțiuni și argumente

Opțiune / Parametru	Descriere
-it	Deschide sesiunea interactivă în containerul de debug.
--image=IMG	Imaginea cu unelte (ex. busybox:1.36, nicolaka/netshoot, ubuntu:24.04).
--target=CONTAINER	Împarte namespace-ul de procese cu containerul țintă (îi vezi procesele și fișierele în /proc/1/root).
--copy-to=POD_NOU	Creează un pod clonă în loc să modifice pod-ul existent.
--share-processes	Cu --copy-to, activează partajarea proceselor între containere.
--profile=general|baseline|netadmin|restricted|sysadmin	Profilul de permisiuni (securityContext) al containerului de debug (kubectl 1.27+).

Exemple

Exemplul 1: Atașarea unui container cu unelte de rețea la un pod distroless

Din containerul efemer netshoot putem testa DNS-ul și conexiunile exact din rețeaua pod-ului api.

kubectl debug -it api-6f9b8d7c4-lm2vd --image=nicolaka/netshoot --target=api

Ieșire în terminal

Targeting container "api". If you don't see processes from this container it may be because the container runtime doesn't support this feature.
Defaulting debug container name to debugger-8k2m4.
~ # ps aux
PID   USER     TIME  COMMAND
    1 65532     0:03 /app/server
   18 root      0:00 zsh
~ # ss -tlnp
State   Recv-Q  Send-Q   Local Address:Port   Peer Address:Port
LISTEN  0       4096                 *:8080              *:*

Exemplul 2: Clonarea unui pod care crăpă la pornire și înlocuirea comenzii

Noul pod api-dbg pornește cu sleep 1h, ca să putem inspecta liniștiți configurarea.

kubectl debug api-6f9b8d7c4-x7k2p -it --copy-to=api-dbg --container=api -- sh

Ieșire în terminal

/app $ ./server --check-config
Error: missing required env JWT_PUBLIC_KEY

Exemplul 3: Inspectarea unui nod din cluster

Sistemul de fișiere al nodului devine accesibil în /host (și poți rula chroot /host).

kubectl debug node/worker-1 -it --image=ubuntu:24.04

Ieșire în terminal

Creating debugging pod node-debugger-worker-1-7x9p2 with container debugger on node worker-1.
root@worker-1:/# chroot /host journalctl -u kubelet -n 5 --no-pager

Greșeli frecvente

• Containerele efemere atașate unui pod nu pot fi șterse individual; ele dispar doar când pod-ul în sine este recreat.
• Uitarea ștergerii pod-urilor create cu --copy-to sau pe noduri (kubectl delete pod api-dbg) după ce ai terminat investigația.

Comenzi înrudite

• kubectl exec: Execută o comandă sau deschide un shell interactiv într-un container care rulează.
• kubectl logs: Afișează sau urmărește în timp real ieșirea standard (stdout/stderr) a containerelor.
• kubectl describe: Afișează detaliile complete ale unei resurse, inclusiv evenimentele recente asociate.
• Obiectul Pod: Cea mai mică unitate de execuție în Kubernetes: unul sau mai multe containere care împart IP-ul și volumele.