Risoluzione dei Problemi di Fallimento dei Pod Kubernetes: Una Guida Completa

La risoluzione dei problemi di fallimento dei pod Kubernetes riguarda meno la memorizzazione di ogni stato e più l'apprendimento di dove Kubernetes lascia indizi. Un pod quasi mai fallisce "silenziosamente". Lo scheduler, il kubelet, il runtime del container, il registro delle immagini, il plugin di volume e la tua applicazione lasciano tutti tracce in posti diversi. Il trucco è controllarli nell'ordine giusto in modo da non passare venti minuti a leggere i log dell'applicazione per un pod che non ha mai estratto la sua immagine.

Di solito inizio con una domanda: il pod è fallito prima che il container iniziasse, mentre il container stava iniziando, o dopo che l'applicazione ha iniziato a funzionare? Questa singola suddivisione mantiene l'indagine concreta. Pending di solito indica problemi di scheduling, storage o configurazione dell'immagine. ImagePullBackOff indica il percorso del registro, il tag, le credenziali o l'uscita del nodo. CrashLoopBackOff di solito significa che il processo inizia e poi esce, anche se il motivo potrebbe essere la configurazione, un file mancante, un comando errato, una dipendenza fallita o pressione sulla memoria.

---

I Tre Pilastri della Diagnosi dei Pod

La risoluzione dei problemi inizia utilizzando tre comandi primari di kubectl per raccogliere tutte le informazioni disponibili sul Pod in fallimento.

1. Controllo dello Stato Iniziale (kubectl get pods)

Il primo passo è sempre determinare lo stato corrente del Pod e dei suoi container. Presta molta attenzione alle colonne STATUS e READY.

kubectl get pods -n my-namespace

Interpretazione dello Stato del Pod

Stato	Significato	Azione Iniziale
Running	Almeno un container è in esecuzione; questo non significa sempre che l'app stia servendo traffico.	Controlla READY, riavvii ed eventi di readiness.
Pending	Il Pod è stato accettato da Kubernetes ma i container non sono ancora stati creati.	Controlla gli eventi di scheduling o lo stato di pull dell'immagine.
CrashLoopBackOff	Il container si avvia, si blocca e Kubelet tenta di riavviarlo ripetutamente.	Controlla i log dell'applicazione (kubectl logs --previous).
ImagePullBackOff	Kubelet non può estrarre l'immagine del container richiesta.	Controlla il nome dell'immagine, il tag e le credenziali del registro.
Error	Il Pod è uscito a causa di un errore di runtime o di un comando di avvio fallito.	Controlla i log e gli eventi describe.
Terminating/Unknown	Il Pod si sta spegnendo o l'host Kubelet non risponde.	Controlla la salute del nodo.

2. Ispezione Approfondita (kubectl describe pod)

Se lo stato è diverso da Running, il comando describe fornisce un contesto cruciale, dettagliando le decisioni di scheduling, l'allocazione delle risorse e gli stati dei container.

kubectl describe pod [POD_NAME] -n my-namespace

Concentrati su queste sezioni nell'output:

• Containers/Init Containers: Controlla lo State (specialmente Waiting o Terminated) e il Last State (dove spesso è registrato il motivo del fallimento, ad es., Reason: OOMKilled).
• Resource Limits: Verifica che Limits e Requests siano impostati correttamente.
• Events: Questa è la sezione più critica. Gli eventi mostrano la cronologia del ciclo di vita, inclusi fallimenti di scheduling, problemi di montaggio del volume e tentativi di pull dell'immagine.

Suggerimento: Se la sezione Events mostra un messaggio come "0/N nodes available," è probabile che il Pod non riesca a essere schedulato a causa di risorse insufficienti (CPU, memoria) o regole di affinità non soddisfatte.

Leggi gli eventi dal basso verso l'alto quando vuoi l'indizio più recente, ma non ignorare gli eventi più vecchi. Un pod può avere più di un problema. Ad esempio, un deployment può iniziare con FailedScheduling perché la memoria richiesta è troppo alta, poi passare a ImagePullBackOff dopo l'aggiunta di un nodo. Se guardi solo lo stato finale, potresti perdere il cambiamento che ha fatto progredire il problema.

3. Revisione dei Log (kubectl logs)

Per problemi di runtime dell'applicazione, i log forniscono il traceback dello stack o i messaggi di errore che spiegano perché il processo è terminato.

# Controlla i log correnti del container
kubectl logs [POD_NAME] -n my-namespace

# Controlla i log per un container specifico all'interno del Pod
kubectl logs [POD_NAME] -c [CONTAINER_NAME] -n my-namespace

# Cruciale per CrashLoopBackOff: Controlla i log del *precedente* run fallito
kubectl logs [POD_NAME] --previous -n my-namespace

Se il pod ha sidecar, includi sempre -c. Molte indagini frustranti derivano dalla lettura dei log del sidecar sano invece del container dell'applicazione in fallimento. Per i fallimenti degli init container, usa il nome dell'init container con -c allo stesso modo:

kubectl logs [POD_NAME] -c [INIT_CONTAINER_NAME] -n my-namespace

---

Scenari Comuni di Fallimento dei Pod e Soluzioni

La maggior parte dei fallimenti dei Pod rientra in alcuni modelli riconoscibili, ciascuno dei quali richiede un approccio diagnostico mirato.

Scenario 1: CrashLoopBackOff

Questo è il fallimento più frequente dei Pod. Significa che il container sta iniziando con successo, ma l'applicazione all'interno del container sta uscendo immediatamente (con un codice di uscita diverso da zero).

Diagnosi:

1. Usa kubectl logs --previous per visualizzare il traceback o il motivo dell'uscita.
2. Usa kubectl describe per controllare il Exit Code nella sezione Last State.

Cause Comuni e Correzioni:

• Codice di Uscita 1/2: Errore generale dell'applicazione, file di configurazione mancante, fallimento di connettività del database o crash dell'applicazione a causa di input errati.
  • Correzione: Debug del codice dell'applicazione o controllo dei ConfigMap/Secret montati.
• Dipendenze Mancanti: Lo script di entry point richiede file o ambienti che non sono presenti.
  • Correzione: Verifica il Dockerfile e il processo di build dell'immagine.
• Comando o argomenti errati: L'immagine del container è valida, ma il comando nella specifica del Pod sovrascrive l'entrypoint dell'immagine in modo errato.
  • Correzione: Confronta il command e gli args del Deployment con il comando di avvio previsto dell'immagine. Testa la stessa immagine localmente se possibile.
• Riavvii indotti dai probe: Un liveness probe potrebbe uccidere un'app che si avvia lentamente prima che finisca di riscaldarsi.
  • Correzione: Aumenta initialDelaySeconds, usa un startupProbe o punta il probe a un endpoint di salute più economico.

Un pattern pratico è distribuire una copia temporanea con la stessa immagine ma un comando innocuo, quindi ispezionare il filesystem e l'ambiente:

kubectl run debug-image \
  --image=registry.example.com/app:tag \
  --restart=Never \
  --command -- sleep 3600

kubectl exec -it debug-image -- /bin/sh

Questo non sostituisce la correzione del Deployment, ma aiuta a rispondere rapidamente a domande semplici: il file di configurazione è effettivamente nell'immagine, il binario esiste, il container ha la shell prevista e le variabili d'ambiente sono presenti?

Scenario 2: ImagePullBackOff / ErrImagePull

Questo si verifica quando Kubelet non può recuperare l'immagine del container specificata nella definizione del Pod.

Diagnosi:

1. Controlla la sezione Events di kubectl describe per il messaggio di errore specifico (ad es., 404 Not Found o authentication required).

Cause Comuni e Correzioni:

• Errore di Battitura o Tag Errato: Il nome o il tag dell'immagine è errato.
  • Correzione: Correggi il nome dell'immagine nella specifica del Deployment o del Pod.
• Accesso a Registro Privato: Il cluster non ha le credenziali per estrarre da un registro privato (come Docker Hub, GCR, ECR).
  • Correzione: Assicurati che un imagePullSecret appropriato sia referenziato nella specifica del Pod e che il Secret esista nel namespace.

# Esempio di snippet di specifica Pod per l'uso di un pull secret
spec:
  containers:
  ...
  imagePullSecrets:
  - name: my-registry-secret

Controlla anche dove risiede il pull secret. I secret di Kubernetes sono con namespace. Un secret chiamato regcred in default non aiuterà un pod in payments. Se la stessa immagine funziona in un namespace ma fallisce in un altro, confronta i service account e i pull secret delle immagini prima di presumere che il registro sia rotto:

kubectl get serviceaccount default -n payments -o yaml
kubectl get secret regcred -n payments

Scenario 3: Stato Pending (Bloccato)

Un Pod rimane in stato Pending, di solito indicando che non può essere schedulato su un Nodo o che sta aspettando risorse (come un PersistentVolume).

Diagnosi:

1. Esegui kubectl describe e guarda la sezione Events.

Cause Comuni e Correzioni:

• Esaurimento delle Risorse: Il cluster manca di Nodi con abbastanza CPU o Memoria disponibile per soddisfare le requests del Pod.
  • Correzione: Aumenta la dimensione del cluster o riduci le richieste di risorse del Pod (se fattibile).
  • Esempio di Messaggio Evento: 0/4 nodes are available: 4 Insufficient cpu.
• Problemi di Binding del Volume: Il Pod richiede un PersistentVolumeClaim (PVC) che non può essere associato a un PersistentVolume (PV) sottostante.
  • Correzione: Controlla lo stato del PVC (kubectl get pvc) e assicurati che StorageClass funzioni.
• Disallineamento del Selettore o dell'Affinità: Il pod richiede un'etichetta del nodo che non esiste, o una regola di affinità richiesta esclude ogni nodo.
  • Correzione: Confronta nodeSelector, nodeAffinity e le etichette del nodo con kubectl get nodes --show-labels.
• Taint non tollerati: I nodi sono disponibili, ma respingono questo pod perché manca di una tollerazione corrispondente.
  • Correzione: Aggiungi la tollerazione prevista al pod, o rimuovi il taint se non rappresenta più una regola di posizionamento reale.

Scenario 4: OOMKilled (Ucciso per Mancanza di Memoria)

Sebbene ciò di solito risulti in uno stato CrashLoopBackOff, la causa sottostante è specifica: il container ha utilizzato più memoria del limite definito nella sua specifica, causando la terminazione forzata da parte del sistema operativo host (tramite Kubelet).

Diagnosi:

1. Controlla kubectl describe -> Last State -> Reason: OOMKilled.

Correzioni:

1. Aumenta i Limiti: Aumenta il limit di memoria nella specifica del Pod, fornendo più margine.
2. Ottimizza l'Applicazione: Profila l'applicazione per ridurre il suo footprint di memoria.
3. Imposta Requests: Assicurati che le requests siano impostate vicine all'effettivo utilizzo a regime per migliorare l'affidabilità dello scheduling.

resources:
  limits:
    memory: "512Mi" # Aumenta questo valore
  requests:
    memory: "256Mi"

Fai attenzione alle "correzioni" di memoria che aumentano solo il limite. Se l'applicazione ha una perdita, un limite più alto potrebbe solo ritardare il prossimo fallimento e far sì che il nodo porti più rischio. Osserva la memoria nel tempo nel tuo sistema di metriche. Un pattern a dente di sega che torna alla linea di base dopo la garbage collection è diverso da una salita costante fino a OOM.

Scenario 5: CreateContainerConfigError e CreateContainerError

Questi stati sono facili da trascurare perché non suonano come fallimenti dell'applicazione. Di solito significano che il kubelet non ha potuto assemblare la configurazione del container.

Le cause comuni includono:

• Un ConfigMap o Secret referenziato non esiste nel namespace.
• Una chiave all'interno di un ConfigMap o Secret è scritta male.
• Un percorso di mount del volume è in conflitto con un altro mount.
• Il container fa riferimento a un contesto di sicurezza non valido.

Il controllo più veloce è ancora describe:

kubectl describe pod [POD_NAME] -n my-namespace

Cerca messaggi di evento come secret "app-config" not found o configmap "settings" not found. Quindi verifica l'oggetto:

kubectl get secret app-config -n my-namespace
kubectl get configmap settings -n my-namespace -o yaml

Questo è un errore comune nella pipeline di deployment. Il manifest dell'applicazione viene applicato, ma il passaggio di creazione del secret è fallito o è stato eseguito contro il namespace sbagliato.

Scenario 6: In Esecuzione ma Non Pronto

Un pod può mostrare Running pur essendo ancora inutilizzabile. La colonna READY ti dice quanti container sono pronti secondo i loro readiness probe. Un pod con 1/2 o 0/1 può essere vivo ma rimosso dagli endpoint del Service.

Controlla gli endpoint quando il traffico fallisce ma i pod sembrano vivi:

kubectl get endpoints [SERVICE_NAME] -n my-namespace
kubectl describe pod [POD_NAME] -n my-namespace

Se l'elenco degli endpoint è vuoto, il problema potrebbe essere un readiness probe, un disallineamento del selettore del Service o l'applicazione in ascolto su una porta diversa da quella prevista dal Service. Negli incidenti reali, è qui che le persone perdono tempo: continuano a riavviare i pod anche se i pod non sono il motivo per cui il traffico manca.

---

Prevenire Fallimenti Futuri: Best Practices

Applicazioni robuste richiedono una configurazione attenta per prevenire comuni insidie di deployment.

Usa Liveness e Readiness Probe

L'implementazione corretta dei probe permette a Kubernetes di gestire intelligentemente la salute del container:

• Liveness Probes: Determinano se il container è sano abbastanza per continuare a funzionare. Se il liveness probe fallisce, Kubelet riavvierà il container (risolvendo soft lock).
• Readiness Probes: Determinano se il container è pronto a servire traffico. Se il readiness probe fallisce, il Pod viene rimosso dagli endpoint del servizio, prevenendo richieste fallite mentre il container si riprende.

Non puntare i liveness probe a controlli di dipendenza profondi a meno che tu non voglia davvero che Kubernetes riavvii il container ogni volta che quella dipendenza ha un breve periodo di inattività. Un database non disponibile per trenta secondi di solito non è la prova che il processo sia morto. Readiness è il posto migliore per dire, "non inviare traffico a questo pod in questo momento."

Applica Limiti e Richieste di Risorse

Definisci sempre i requisiti di risorse per i container. Questo impedisce ai Pod di consumare risorse eccessive (portando all'instabilità del Nodo) e assicura che lo scheduler possa posizionare il Pod su un Nodo con capacità sufficiente.

Utilizza Init Containers per la Configurazione

Se un Pod richiede un controllo delle dipendenze o una configurazione dei dati prima che l'applicazione principale inizi (ad es., attendere il completamento di una migrazione del database), usa un Init Container. Se l'Init Container fallisce, il Pod lo riavvierà ripetutamente, isolando pulitamente gli errori di configurazione dagli errori di runtime dell'applicazione.

Un Flusso di Triage Pratico

Quando sei di turno, usa un percorso ripetibile:

1. Controlla kubectl get pods -n <namespace> -o wide in modo da vedere stato, riavvii, età e posizionamento del nodo.
2. Esegui kubectl describe pod e leggi Eventi, Stato, Ultimo Stato, mount e impostazioni delle risorse.
3. Estrai i log con kubectl logs, aggiungendo --previous per i container riavviati e -c per i pod multi-container.
4. Se il pod è Pending, ispeziona scheduling, taint, etichette del nodo e PVC prima di leggere i log dell'app.
5. Se il pod è Running ma non riceve traffico, ispeziona readiness probe, selettori del Service ed endpoint.
6. Se il pod è stato OOMKilled, confronta i limiti con i grafici di memoria reali prima di semplicemente aumentare il numero.

Questo ordine ti impedisce di saltare direttamente all'applicazione quando Kubernetes non l'ha ancora nemmeno avviata.

Controllo Finale

L'abitudine più utile è separare i sintomi dalle cause. CrashLoopBackOff è un sintomo. La causa potrebbe essere un secret mancante, una migrazione errata, un liveness probe o un limite di memoria. Pending è un sintomo. La causa potrebbe essere richieste di CPU, un PVC, un taint o un selettore di nodo. Lascia che lo stato del pod ti dica dove guardare, poi lascia che eventi e log ti dicano cosa è cambiato.