kubectl debug: la guida completa al troubleshooting di pod e nodi

kubectl debug vs kubectl logs vs kubectl describe

kubectl debug, kubectl logs e kubectl describe sono tutti comandi di troubleshooting, ma hanno scopi diversi. kubectl logs recupera l'output dell'applicazione, kubectl describe mostra i dettagli e gli eventi delle risorse Kubernetes, mentre kubectl debug offre accesso interattivo per un'analisi in tempo reale.

kubectl logs

Il comando kubectl logs mostra l'output stdout e stderr dei container. Viene comunemente usato per individuare crash dell'applicazione, errori di avvio o errori a runtime.

kubectl logs my-pod

Per i pod con più container, specificare il nome del container:

kubectl logs my-pod -c app-container

Questo comando è leggero e sicuro, perché non modifica il pod né crea nuovi container.

kubectl describe

Il comando kubectl describe fornisce informazioni dettagliate sulle risorse Kubernetes, tra cui label, condizioni, volumi montati ed eventi recenti.

kubectl describe pod my-pod

È utile per diagnosticare problemi come:

• Scheduling non riuscito
• Errori di pull dell'immagine
• Probe non superate
• Vincoli sulle risorse
• Eventi di CrashLoopBackOff

A differenza di kubectl logs, si concentra sullo stato degli oggetti Kubernetes anziché sull'output dell'applicazione.

kubectl debug

Il comando kubectl debug consente il troubleshooting interattivo collegando container effimeri o creando pod di debug temporanei.

kubectl debug my-pod -it --image=busybox

Questo approccio è utile quando log e descrizioni delle risorse non bastano. Ad esempio, permette di:

• Verificare la connettività di rete
• Esaminare il contenuto del filesystem
• Eseguire strumenti di ispezione dei processi
• Eseguire il debug di container minimali privi di shell
• Analizzare problemi a livello di nodo

Poiché crea ambienti di debug temporanei, kubectl debug offre un accesso più approfondito rispetto agli altri comandi, riducendo al minimo le modifiche ai workloads di produzione.

Esempi pratici di kubectl debug

Eseguire il debug della connettività di rete

Usare un container di debug per testare DNS, service discovery e accesso di rete in uscita dal namespace di rete del pod.

kubectl debug my-pod -it --image=busybox --target=my-container

All'interno del container di debug, eseguire comandi come:

nslookup kubernetes.default
wget -qO- http://my-service.default.svc.cluster.local
ping 10.0.0.10

È utile quando l'immagine dell'applicazione non include strumenti come nslookup, curl o ping.

Eseguire il debug di un pod in CrashLoopBackOff

Per un pod che continua a riavviarsi, creare una copia da ispezionare. In questo modo si evita di modificare il workload originale.

kubectl debug my-pod --copy-to=my-pod-debug -it --image=ubuntu

Dal pod copiato è possibile ispezionare variabili d'ambiente, file montati, configurazione e accesso di rete:

env
ls -la /etc/config
cat /etc/config/app.conf

Questo aiuta a individuare file mancanti, valori d'ambiente errati o dipendenze a runtime.

Eseguire il debug con la condivisione del namespace dei processi

Usare la condivisione del namespace dei processi quando è necessario ispezionare i processi di un altro container del pod.

kubectl debug my-pod \
  --copy-to=my-pod-debug \
  --share-processes \
  -it \
  --image=ubuntu

All'interno del container di debug, controllare i processi in esecuzione:

ps aux
top

È utile per ispezionare processi bloccati, processi zombie o processi figli inattesi.

Eseguire il debug con un'immagine personalizzata

Usare un'immagine di debug personalizzata quando le immagini standard non includono gli strumenti necessari.

kubectl debug my-pod -it \
  --image=my-registry.example.com/debug-tools:latest \
  --target=my-container

Un'immagine personalizzata può includere strumenti come curl, dig, tcpdump, strace o client per database. In questo modo le immagini di produzione restano leggere, pur consentendo un troubleshooting più approfondito quando serve.

Best practice per l'uso di kubectl debug

Ecco alcune pratiche utili da considerare quando si usa questo comando.

1. Partire dall'osservabilità prima di entrare nel pod

Usare kubectl logs, kubectl describe, eventi, metriche e trace prima di avviare una sessione di debug interattiva. Questi strumenti sono più rapidi, più sicuri e spesso sufficienti a individuare il problema.

kubectl logs my-pod
kubectl describe pod my-pod
kubectl get events --sort-by=.metadata.creationTimestamp

Questo aiuta a capire se il problema è causato dall'applicazione, dallo scheduling, dalle probe, dai limiti di risorse, dalla rete o dalla configurazione di Kubernetes. Ad esempio, kubectl describe può mostrare errori di pull dell'immagine, readiness probe non superate o errori di mount dei volumi prima ancora di dover ispezionare direttamente il container.

Usare kubectl debug quando i segnali disponibili non spiegano il problema o quando è necessario esaminare lo stato a runtime dall'interno dell'ambiente del pod.

2. Usare i container effimeri per ispezionare, non per modificare l'applicazione

I container effimeri sono pensati per il troubleshooting. Non vanno usati per applicare patch ai file, riavviare servizi, installare dipendenze o cambiare il comportamento dell'applicazione in un workload in esecuzione.

Vanno usati per ispezionare lo stato, eseguire comandi diagnostici e raccogliere evidenze:

kubectl debug my-pod -it --image=busybox --target=my-container

Ad esempio, è possibile verificare la risoluzione DNS, ispezionare i file montati, testare la connettività verso i servizi o visualizzare i processi in esecuzione. Queste azioni aiutano a capire cosa sta succedendo senza modificare il workload.

Qualsiasi correzione va apportata nel codice sorgente, nell'immagine container, nei manifest o nella pipeline di deployment. In questo modo il comportamento in produzione resta riproducibile e si evitano modifiche manuali una tantum che scompaiono al riavvio del pod.

3. Preferire i container di debug all'aggiunta di strumenti nelle immagini di produzione

Evitare di installare shell, package manager e strumenti di rete nelle immagini di produzione solo per il troubleshooting. Questi strumenti aumentano le dimensioni dell'immagine e possono ampliare la superficie di attacco del container.

Meglio mantenere leggere le immagini dell'applicazione e usare un'immagine di debug separata quando serve:

kubectl debug my-pod -it --image=nicolaka/netshoot --target=my-container

È particolarmente utile con le immagini minimali, come i container distroless o basati su scratch, che spesso non includono una shell. Un container di debug può fornire strumenti come curl, dig, tcpdump, ss e ip senza modificare l'immagine di produzione.

Questo approccio mantiene anche un confine netto: l'immagine dell'applicazione esegue il workload, mentre l'immagine di debug si usa solo durante sessioni di troubleshooting controllate.

4. Usare immagini di debug approvate e sicure

Le immagini di debug spesso includono strumenti potenti come tcpdump, strace, curl, dig, package manager e utility della shell. Usare solo immagini approvate provenienti da registry affidabili.

Fissare le versioni delle immagini anziché usare tag variabili:

kubectl debug my-pod -it --image=registry.example.com/debug-tools:1.4.2

Le immagini approvate dovrebbero essere sottoposte a scansione per le vulnerabilità e mantenute aggiornate. Dovrebbero contenere gli strumenti di cui i team hanno effettivamente bisogno, senza pacchetti superflui.

Anche l'accesso va controllato tramite RBAC. Non tutti gli utenti dovrebbero poter creare container effimeri, collegarsi a workloads sensibili o avviare sessioni di debug a livello di nodo. Il debug dei nodi può esporre il filesystem dell'host e informazioni a livello di sistema, quindi dovrebbe essere riservato a operatori affidabili — abbinandolo, dove possibile, al flag --profile (restricted o baseline) per evitare di concedere più accesso di quanto la sessione richieda.

5. Ripulire i pod di debug e documentare la sessione

Rimuovere i pod di debug copiati al termine del troubleshooting, per evitare disordine e un consumo inutile di risorse.

kubectl delete pod my-pod-debug

I container effimeri aggiunti ai pod esistenti non possono essere rimossi dalla spec del pod, ma smettono di essere eseguiti al termine della sessione di debug. I pod copiati, invece, restano nel cluster finché non vengono eliminati.

Annotare cosa è stato verificato, quali comandi sono stati eseguiti e cosa è emerso. Questo rende l'incidente più facile da rivedere e aiuta a migliorare i runbook per i problemi futuri.

Note efficaci dovrebbero includere il pod o il nodo interessato, l'immagine di debug utilizzata, l'output dei comandi rilevanti e la causa finale. Così altri Engineers evitano di ripetere la stessa indagine in seguito.

Ridurre il debugging manuale risolvendo proattivamente i rischi di resilienza con PerfectScale

Comandi come kubectl debug sono indispensabili quando serve analizzare in tempo reale un pod in crash, un processo bloccato o un problema a livello di nodo, ma la maggior parte di questi incidenti nasce da configurazioni errate delle risorse che avrebbero potuto essere individuate prima. PerfectScale potenzia in modo autonomo resilienza e prestazioni di Kubernetes grazie al right-sizing dei workloads, prevenendo i downtime e ottimizzando l'uso delle risorse per una disponibilità del 99,99%: il team dedica così meno tempo alle sessioni di debug interattive e più tempo al rilascio. Invece di aspettare che un pod vada in errore per poi ricorrere ai container effimeri, PerfectScale identifica e corregge alla radice i rischi di resilienza che causano quei guasti.

Funzionalità chiave di PerfectScale:

• Correzione automatica dei problemi: identifica e risolve all'istante i rischi di resilienza per massimizzare l'uptime ed eliminare la latenza, prevenendo errori di configurazione (assenza di CPU request, memory request o memory limit) e problemi di under-provisioning delle risorse come OOM, throttling della CPU ed eviction.
• Hardening dell'infrastruttura: offre visibilità completa sui nodi per far emergere in modo proattivo le configurazioni errate, prevenire l'over-commitment dei nodi con raccomandazioni precise sui memory limit, validare node affinity e taint e scegliere i tipi di nodo più adatti ai pod.
• Prioritizzazione basata sull'impatto: concentra il team sui problemi più critici in tempo reale grazie all'auto-prioritizzazione avanzata e allinea gli alert a SLA e SLO, così i livelli di servizio restano in linea con gli obiettivi.
• Alert in tempo reale e integrazioni di ticketing: invia notifiche istantanee tramite Slack, MS Teams o Datadog e consente di inserire qualsiasi problema in un flusso di lavoro consolidato creando un ticket con un clic.
• Copertura estesa dei rischi: rileva in modo continuo eviction, out of memory, sospetti memory leak, throttling della CPU, riavvii dei pod, HPA che raggiunge il numero massimo di repliche e request/limit di CPU e memoria sottodimensionati o non impostati.

Scopra come PerfectScale può mantenere stabili i suoi cluster e ridurre la necessità di troubleshooting manuale sulla piattaforma di ottimizzazione delle prestazioni Kubernetes.

FAQ

A cosa serve il comando kubectl debug?

kubectl debug serve al troubleshooting interattivo dei workloads e dei nodi Kubernetes. Può collegare un container effimero a un pod in esecuzione, creare una copia modificata di un pod in crash o avviare un pod di debug su un nodo — il tutto senza che gli strumenti di debug debbano essere già integrati nell'immagine di destinazione.

Come si usa kubectl debug su un pod?

Eseguire kubectl debug <pod-name> -it --image=busybox per collegare un container di debug effimero a un pod in esecuzione. Aggiungere --target=<container-name> per condividere il namespace dei processi con un container specifico, oppure --copy-to=<new-pod-name> per eseguire il debug su una copia anziché sul pod attivo (utile per i pod che vanno in crash all'avvio).

Come si usa kubectl debug su un nodo?

Eseguire kubectl debug node/<node-name> -it --image=ubuntu per creare un pod di debug eseguito nei namespace host del nodo, con il filesystem root del nodo montato in /host. Per impostazione predefinita usa il profilo general, che non concede accesso privilegiato — usare --profile=sysadmin se servono capability root complete.

Qual è la sintassi del comando kubectl debug?

La forma generale è kubectl debug (POD | TYPE/NAME) [flags], usata più comunemente con --image per impostare l'immagine del container di debug, -it per un terminale interattivo, --target per selezionare un container specifico e --copy-to per eseguire il debug su una copia del pod.

In cosa kubectl debug è diverso da kubectl exec?

kubectl exec esegue un comando all'interno di un container esistente con l'immagine propria del pod, quindi funziona solo se quell'immagine include già gli strumenti necessari. kubectl debug collega un container (o un pod) separato con l'immagine desiderata, il che è essenziale per i container minimali o distroless che non hanno alcuna shell.

kubectl debug modifica il pod originale o i suoi container?

L'aggiunta di un container effimero con kubectl debug non riavvia né modifica i container esistenti del pod: si limita ad aggiungere accanto a essi un container temporaneo. L'uso di --copy-to va oltre e crea un pod separato, lasciando l'originale completamente intatto.

È necessario ripulire i pod creati da kubectl debug?

Sì, per tutti i pod creati con --copy-to. Quei pod restano nel cluster finché non vengono eliminati con kubectl delete pod <debug-pod-name>. I container effimeri aggiunti direttamente a un pod esistente non richiedono una pulizia separata: smettono di essere eseguiti al termine della sessione, anche se restano elencati nella spec del pod.