TL;DR
Quando qualcosa non funziona in Kubernetes, segui sempre questo ordine:
-
Il pod è in Running? -->
kubectl logs -
Il pod è in CrashLoopBackOff, Pending o non parte? -->
kubectl describe pod -
Ancora nulla di chiaro? -->
kubectl get events
Questo flusso risolve la maggioranza dei problemi quotidiani.
Perché il debugging in Kubernetes sembra sempre complicato
Se lavori con Kubernetes, probabilmente ti è già successo che
l’applicazione non risponde, qualcosa è rotto e tu inizi a saltare tra dashboard, metriche, YAML e configurazioni senza una direzione chiara.
Il problema non è Kubernetes in sé.
Il problema è non avere un punto di partenza chiaro.
Il debugging efficace non consiste nel conoscere mille comandi, ma nel farsi la domanda giusta al momento giusto. In Kubernetes, la domanda iniziale è sempre la stessa:
Il pod sta girando o no?
Da questa risposta dipende tutto il resto.
Il framework di debugging in 3 passi
Questo metodo è volutamente semplice.
Non copre il 100% dei casi possibili, ma copre quasi tutti quelli reali che incontri nel lavoro quotidiano.
L’idea è questa:
- prima controlli l’applicazione
- poi controlli Kubernetes
- infine controlli il cluster
Step 1 – Il pod è in esecuzione? Parti dai log
Se il pod è in stato Running, Kubernetes ha fatto il suo lavoro.
A questo punto il problema è molto probabilmente dentro il container.
Il comando da usare è:
kubectl logs <nome-pod>
La domanda a cui stai rispondendo è:
L’applicazione è partita correttamente?
Qui trovi:
- errori di avvio
- stack trace
- configurazioni sbagliate
- variabili d’ambiente mancanti
- problemi di connessione a servizi esterni
👉 Regola pratica:
se il pod è Running e non funziona come dovrebbe, parti sempre dai log.
Se i log sono vuoti o il container non parte nemmeno, passa subito al passo 2.
Step 2 – Il pod non parte o va in crash? Chiedi a Kubernetes
Se vedi stati come:
CrashLoopBackOffErrImagePullPendingImagePullBackOff-
ContainerCreatingche non finisce mai
allora il problema non è il tuo codice, ma qualcosa che Kubernetes non riesce a fare.
Usa:
kubectl describe pod <nome-pod>
La domanda qui è:
Perché Kubernetes non riesce a far girare questo pod?
Con describe scopri:
- errori nei probe (liveness / readiness)
- problemi con l’immagine del container
- errori nel montaggio dei volumi
- limiti di risorse (CPU / memoria)
- scheduling fallito
La parte più importante è la sezione Events alla fine:
è la “cronologia delle decisioni” prese da Kubernetes su quel pod.
👉 Regola pratica:
se il pod non è Running, describe viene prima dei log.
Step 3 – Il pod sembra a posto, ma qualcosa non torna? Guarda il cluster
Se log e describe non spiegano il problema, è il momento di allargare lo sguardo.
A volte il tuo pod è solo una vittima collaterale di un problema più grande.
Usa:
kubectl get events -A --sort-by=.metadata.creationTimestamp
La domanda finale è:
Cos’altro sta succedendo nel cluster?
Qui puoi trovare:
- nodi sotto pressione (memoria, disco, CPU)
- problemi di rete (CNI)
- pod evicted (preemption)
- problemi su storage o controller di sistema
Gli eventi sono una timeline: leggerli in ordine temporale spesso chiarisce dinamiche che non vedi guardando un singolo pod.
3. La checklist mentale da memorizzare
Se devi ricordare solo una cosa, ricorda questa sequenza:
Running? --> logs
Crash / Pending? --> describe
Ancora dubbi? --> events
Non è magia, è metodo.
Conclusione: meno panico, più metodo
Il debugging in Kubernetes diventa frustrante quando inizi a guardare tutto contemporaneamente.
Diventa gestibile quando segui un percorso chiaro.
Questo framework non elimina i problemi, ma elimina:
- il panico
- il debugging casuale
- le ore perse “a tentativi”
- copia/incolla il problema in chatgpt
La prossima volta che qualcosa non funziona, fermati un attimo e riparti dalla domanda più semplice:
Il pod sta girando o no?
Da lì, il resto viene molto più naturale.
Buon debugging 💪
Top comments (0)