Troubleshooting di Kubernetes: comandi, errori e soluzioni pratiche

TLDR:
Il troubleshooting di Kubernetes procede dal basso verso l'alto: verificare lo stato dei pod, ispezionare gli eventi, consultare i log e, se necessario, passare al debug interattivo. La maggior parte dei problemi si riconduce a una manciata di errori ricorrenti (ImagePullBackOff, CrashLoopBackOff, Pending, OOMKilled), tutti rintracciabili con kubectl describe/logs. Per prevenire i problemi ricorrenti è fondamentale impostare correttamente request e limit delle risorse, calibrare le probe, monitorare in modo continuo e fare right-sizing dei workloads nel tempo.

Codici di errore comuni di Kubernetes e come risolverli

ImagePullBackOff

Problema: ImagePullBackOff si verifica quando Kubernetes non riesce a scaricare l'immagine del container necessaria per avviare un pod. Dopo il primo tentativo fallito, Kubernetes riprova l'operazione con ritardi progressivamente più lunghi. Finché l'immagine non diventa disponibile, il pod non entra in esecuzione.

Diagnosi: gli errori di pull delle immagini sono comunemente causati da nomi di immagine non validi, tag errati, credenziali del registry mancanti, token di autenticazione scaduti, disservizi del registry o problemi di connettività di rete. Il punto di partenza più utile è la sezione Events della descrizione del pod.

Eseguire kubectl describe pod <pod-name> e cercare messaggi come ErrImagePull, pull access denied, unauthorized o manifest unknown. Questi messaggi indicano solitamente se il problema riguarda l'autenticazione, la disponibilità dell'immagine o la connettività.

Workflow di risoluzione:

1. Eseguire kubectl describe pod <pod-name> ed esaminare la sezione Events.
2. Verificare che nome e tag dell'immagine siano corretti ed esistano nel registry.
3. Confermare che il container registry sia raggiungibile dai nodi del cluster.
4. Validare gli image pull secret configurati sul pod o sul service account.
5. Controllare credenziali del registry, permessi e stato di scadenza dei token.
6. Verificare la risoluzione DNS e la connettività di rete in uscita dai worker node.
7. Esaminare configurazioni di proxy, firewall o network policy che potrebbero bloccare l'accesso al registry.

Esempio

kubectl describe pod my-pod
kubectl get secrets
kubectl describe secret registry-secret

CrashLoopBackOff

Problema: CrashLoopBackOff indica che un container si avvia, termina e viene riavviato da Kubernetes ripetutamente. Dopo diversi errori consecutivi, Kubernetes introduce ritardi crescenti tra i tentativi di riavvio per evitare cicli di restart continui.

Diagnosi: questa condizione è tipicamente causata da errori di avvio dell'applicazione, valori di configurazione non validi, variabili d'ambiente mancanti, inizializzazione delle dipendenze fallita, problemi di connettività al database o comandi del container errati.

I log del container sono di solito il modo più rapido per identificare la causa radice. Esaminare i log con kubectl logs <pod-name>. Se il container si riavvia troppo velocemente, usare il flag --previous per recuperare i log dell'ultima istanza fallita. Anche la descrizione del pod può rivelare cause di terminazione, exit code, numero di riavvii e fallimenti delle probe.

Workflow di risoluzione:

1. Esaminare i log applicativi con kubectl logs <pod-name>.
2. Se necessario, recuperare i log dell'istanza precedente del container con --previous.
3. Ispezionare gli eventi del pod e i dettagli di terminazione con kubectl describe pod <pod-name>.
4. Verificare variabili d'ambiente, file di configurazione, secret e comandi di avvio.
5. Controllare connessioni al database, dipendenze esterne ed endpoint dei servizi.
6. Esaminare i limiti di CPU e memoria alla ricerca di segnali di esaurimento delle risorse.
7. Validare le impostazioni delle probe di readiness, startup e liveness e, se necessario, regolarne le soglie temporali.

Esempio

kubectl logs my-pod
kubectl logs my-pod --previous
kubectl describe pod my-pod

Pending

Problema: un pod entra nello stato Pending quando Kubernetes accetta la definizione del pod ma non riesce ad assegnarlo a un nodo idoneo. Il workload rimane non schedulato e non si avvia finché tutti i requisiti di scheduling non sono soddisfatti.

Diagnosi: i pod in Pending sono causati il più delle volte da risorse insufficienti nel cluster, regole di scheduling restrittive, errori di provisioning dello storage o vincoli di posizionamento sui nodi. I messaggi di scheduling più comuni includono CPU insufficiente, memoria insufficiente, node selector non corrispondenti, conflitti di taint o PersistentVolumeClaim non associati.

Gli eventi di scheduling mostrati da kubectl describe pod <pod-name> identificano tipicamente il motivo esatto per cui lo scheduler non è riuscito a collocare il workload.

Workflow di risoluzione:

1. Eseguire kubectl describe pod <pod-name> ed esaminare gli eventi dello scheduler.
2. Controllare la disponibilità dei nodi con kubectl get nodes.
3. Verificare che nel cluster ci siano risorse CPU e memoria sufficienti.
4. Esaminare node selector, regole di node affinity, taint e toleration.
5. Validare che le label richieste sui nodi siano presenti.
6. Controllare i PersistentVolumeClaims (PVC) e lo stato del provisioning dello storage.
7. Se l'autoscaling è abilitato, confermare che il cluster autoscaler funzioni correttamente.

Esempio

kubectl describe pod my-pod
kubectl get nodes
kubectl get pvc

OOMKilled

Problema: OOMKilled si verifica quando un container supera il limite di memoria configurato e viene terminato dall'out-of-memory (OOM) killer di Linux. Kubernetes applica i limiti di memoria in modo rigoroso, arrestando immediatamente il container quando il limite viene superato.

Diagnosi: l'esaurimento della memoria può derivare da memory leak, caching eccessivo, comportamento inefficiente dell'applicazione, picchi di traffico, dataset di grandi dimensioni o limiti di memoria troppo bassi per il workload.

La descrizione del pod mostra solitamente OOMKilled come motivo di terminazione. Strumenti di monitoraggio delle risorse come Prometheus, Grafana o Metrics Server possono aiutare a determinare se il workload subisce una pressione costante sulla memoria o picchi improvvisi di utilizzo.

Workflow di risoluzione:

1. Confermare il motivo della terminazione con kubectl describe pod <pod-name>.
2. Esaminare le metriche di consumo di memoria precedenti al guasto.
3. Identificare picchi di memoria, leak o utilizzo elevato prolungato.
4. Confrontare l'utilizzo effettivo della memoria con request e limit configurati.
5. Aumentare i limiti di memoria se risultano chiaramente sottodimensionati.
6. Investigare cause a livello applicativo come caching, concorrenza o memory leak.
7. Ottimizzare l'uso della memoria dell'applicazione e regolare le impostazioni delle risorse in base al comportamento osservato del workload.

Esempio

kubectl describe pod my-pod
kubectl top pod my-pod
kubectl top nodes

5 modi per prevenire i problemi di Kubernetes alla radice

I team Kubernetes più esperti progettano i propri cluster in modo da ridurre al minimo i guasti più comuni. Questo favorisce la resilienza e semplifica anche il troubleshooting quando i problemi si presentano.

1. Impostare request e limit delle risorse

Request e limit delle risorse aiutano Kubernetes ad allocare CPU e memoria in modo prevedibile nell'intero cluster. Le request definiscono le risorse minime necessarie per lo scheduling, mentre i limit definiscono le risorse massime che un container può consumare. Una configurazione corretta impedisce ai workloads di competere in modo aggressivo per le risorse condivise.

Senza request, lo scheduler non può prendere decisioni di posizionamento accurate, con il rischio di nodi sovraccarichi e workloads instabili. Senza limit, un singolo container può consumare quantità eccessive di memoria o CPU, penalizzando le altre applicazioni in esecuzione sullo stesso nodo.

Limit configurati con cura aiutano a ridurre il rischio di eventi OOMKilled, throttling della CPU ed esaurimento delle risorse dei nodi. Tuttavia, anche limit troppo bassi possono creare instabilità, penalizzando le applicazioni nei periodi di picco.

L'uso di policy LimitRange e ResourceQuota a livello di namespace aiuta a imporre pratiche di gestione delle risorse coerenti tra team e ambienti. Questi controlli riducono la probabilità che workloads mal configurati compromettano la stabilità del cluster.

2. Usare le probe di readiness e liveness con attenzione

Le probe di readiness e liveness consentono a Kubernetes di determinare se i container sono in salute e pronti a ricevere traffico. Una configurazione corretta delle probe migliora l'affidabilità delle applicazioni, impedendo ai pod non integri di servire richieste e riavviando automaticamente i container in errore.

Le probe di readiness controllano se un pod viene aggiunto all'elenco degli endpoint di un servizio. Se la probe di readiness fallisce, il traffico smette di essere instradato al pod finché non si ripristina. Questo evita che gli utenti raggiungano applicazioni parzialmente inizializzate o degradate.

Le probe di liveness rilevano deadlock dell'applicazione o processi che non rispondono. Quando una probe di liveness fallisce ripetutamente, Kubernetes riavvia automaticamente il container. Questo meccanismo migliora la capacità di auto-riparazione, ma può anche generare instabilità se configurato in modo errato.

Una temporizzazione troppo aggressiva delle probe è una causa frequente di riavvii inutili e condizioni di CrashLoopBackOff. Le applicazioni che richiedono tempi di avvio lunghi potrebbero fallire gli health check prima del completamento dell'inizializzazione. Le startup probe sono spesso utili per i workloads con processi di boot lenti.

3. Monitorare eventi, log e metriche

Il monitoraggio continuo è essenziale per rilevare i problemi di Kubernetes prima che degenerino in disservizi. Log, metriche ed eventi del cluster offrono visibilità sul comportamento dei workloads, sull'utilizzo delle risorse, sullo stato dell'infrastruttura e sui guasti operativi.

Piattaforme di metriche come Prometheus e Grafana aiutano a monitorare utilizzo di CPU, consumo di memoria, riavvii dei pod, latenza di rete e prestazioni dello storage. Osservare i trend nel tempo permette agli Engineers di identificare comportamenti anomali prima che i servizi diventino instabili.

I sistemi di logging centralizzato migliorano il troubleshooting aggregando log dei container, log dei nodi ed eventi di sistema in una piattaforma consultabile. Strumenti come Elasticsearch, Fluent Bit, Loki e Splunk sono comunemente usati per la raccolta e l'analisi dei log di Kubernetes.

Gli eventi di Kubernetes forniscono ulteriore contesto operativo registrando errori di scheduling, errori di pull delle immagini, eviction dei pod e problemi di configurazione. Poiché gli eventi sono temporanei, raccoglierli e archiviarli esternamente migliora le capacità di troubleshooting nel lungo periodo.

4. Usare namespace e label in modo coerente

I namespace aiutano a organizzare i workloads e a isolare le risorse all'interno di un cluster Kubernetes. Un uso coerente dei namespace migliora la chiarezza operativa, il controllo degli accessi, la gestione delle risorse e l'efficienza del troubleshooting.

Separare ambienti come sviluppo, staging e produzione in namespace diversi riduce il rischio di interferenze accidentali tra workloads. Le policy a livello di namespace possono inoltre imporre confini di sicurezza e quote di risorse.

Le label forniscono metadati usati per la selezione, il raggruppamento, il monitoraggio e l'automazione dei workloads. Servizi Kubernetes, deployment, network policy e sistemi di monitoraggio fanno tutti ampio affidamento sulle label per identificare i workloads.

Schemi di labeling incoerenti o mal progettati causano spesso errori di routing dei servizi, confusione nei deployment e complessità operativa. Label standardizzate rendono più semplice cercare, monitorare e gestire i workloads nei cluster di grandi dimensioni.

5. Fare right-sizing continuo dei workloads in base all'utilizzo reale

I requisiti di risorse dei workloads cambiano nel tempo con l'evoluzione delle applicazioni, la variazione dei pattern di traffico e la crescita dell'utilizzo dell'infrastruttura. Il right-sizing continuo dei workloads aiuta a mantenere le prestazioni riducendo lo spreco di risorse del cluster.

I workloads sovradimensionati sprecano CPU e memoria, aumentando i costi dell'infrastruttura e riducendo l'efficienza del cluster. I workloads sottodimensionati generano instabilità, errori di scheduling, throttling della CPU e crash legati alla memoria.

Monitorare il comportamento reale dei workloads fornisce i dati necessari per ottimizzare request e limit delle risorse. Gli Engineers dovrebbero analizzare i pattern di utilizzo di lungo periodo invece di basarsi solo su picchi di breve durata o stime iniziali di deployment.

Strumenti come il Vertical Pod Autoscaler (VPA) possono raccomandare o regolare automaticamente le impostazioni delle risorse in base al consumo osservato. L'Horizontal Pod Autoscaler (HPA) completa questo approccio scalando il numero di repliche in risposta alle variazioni di carico.

Come PerfectScale aiuta a prevenire e risolvere i problemi di Kubernetes

La maggior parte del troubleshooting di Kubernetes è reattiva: si aspetta che un pod vada in crash, poi si scava tra eventi, log e metriche per trovarne la causa. PerfectScale ribalta questo modello facendo right-sizing autonomo dei workloads, prevenendo i tempi di inattività e ottimizzando l'uso delle risorse per mantenere una disponibilità del 99,99%. Invece di inseguire manualmente eventi di OOMKilled, CrashLoopBackOff e throttling, i team DevOps, SRE e platform engineering ottengono una remediation continua e basata sui dati su ogni livello dello stack K8s.

Le funzionalità chiave di PerfectScale:

• Remediation automatica dei problemi: identifica e corregge istantaneamente i rischi per la resilienza per massimizzare l'uptime ed eliminare la latenza, affrontando problemi come OOM, throttling della CPU ed eviction dei pod prima che degenerino in disservizi.
• Prevenzione degli errori di configurazione: intercetta le configurazioni errate all'origine dei guasti più comuni, tra cui CPU request mancanti, memory request mancanti e memory limit non impostati, così che i workloads si avviino e girino in modo affidabile.
• Rilevamento del sottodimensionamento: fa emergere CPU e memoria sottodimensionate (sia request che limit) e sospetti memory leak, le cause radice che tengono i pod bloccati in cicli di restart anche quando i nodi sembrano in salute.
• Rafforzamento dell'infrastruttura: offre visibilità olistica sui nodi per prevenirne l'over-commitment, validare node affinity e taint e scegliere i tipi di nodo ottimali per i Suoi workloads.
• Prioritizzazione guidata dall'impatto: allinea gli alert ai Suoi SLA e SLO, invia notifiche istantanee tramite Slack, MS Teams o Datadog e trasforma un problema in ticket con un solo clic.
• Ottimizzazione dell'autoscaling: mette a punto le configurazioni di autoscaling orizzontale e verticale affinché i trigger di scaling scattino con precisione, prevenendo gli scenari di "HPA al massimo delle repliche" e di esaurimento delle risorse che generano instabilità.

FAQ

Qual è il primo comando da eseguire quando un pod ha problemi? kubectl get pods per individuare il pod in errore, poi kubectl describe pod <pod-name> per i dettagli sul suo stato e sugli eventi recenti.

Cosa causa CrashLoopBackOff? Il container si avvia, termina e si riavvia ripetutamente — di solito per un errore di avvio, una configurazione sbagliata, variabili d'ambiente mancanti o un errore di connessione a un database/una dipendenza. Controllare prima kubectl logs <pod-name> --previous.

Cosa causa ImagePullBackOff? Kubernetes non riesce a scaricare l'immagine del container — spesso per un nome/tag di immagine non valido, credenziali del registry mancanti o scadute, o un problema di rete nel raggiungere il registry.

Perché il mio pod è bloccato in Pending? Lo scheduler non riesce a collocarlo — tipicamente per CPU/memoria insufficienti nel cluster, node selector o taint non corrispondenti, oppure un PersistentVolumeClaim non associato. kubectl describe pod <pod-name> mostra il motivo esatto dello scheduling fallito.

Cosa significa OOMKilled? Il container ha superato il suo limite di memoria ed è stato terminato dall'OOM killer di Linux. Confrontare l'uso della memoria con request/limit configurati e cercare leak o limit sottodimensionati.

Come faccio il debug di problemi di rete o DNS? Usare kubectl get endpoints per confermare che i pod siano associati a un servizio e kubectl exec -it <pod-name> -- nslookup <service-name> per testare la risoluzione DNS dall'interno di un pod.

Come posso prevenire questi problemi invece di limitarmi a reagire? Impostare request/limit delle risorse corretti, configurare con attenzione le probe di readiness/liveness, monitorare in modo continuo log/eventi/metriche, usare namespace e label coerenti e fare right-sizing dei workloads nel tempo (ad esempio con VPA/HPA o uno strumento come PerfectScale).

Pronto a smettere di spegnere incendi su Kubernetes? Esplori la piattaforma di performance e resilienza per Kubernetes di PerfectScale per scoprire come l'ottimizzazione autonoma mantiene i Suoi cluster stabili, resilienti ed efficienti in termini di costi.