Risoluzione dei problemi: Perché il mio Pod Kubernetes è bloccato in stato Pending o CrashLoopBackOff?

Pending e CrashLoopBackOff sembrano simili quando si aspetta un rollout, ma significano cose molto diverse. Pending di solito significa che Kubernetes non è stato in grado di posizionare o preparare il pod. CrashLoopBackOff significa che il contenitore è stato avviato, poi è uscito, e Kubernetes sta ritardando il prossimo riavvio.

Questa differenza è importante. Un pod in sospeso è spesso un problema di scheduler, immagine o storage. Un pod in crash è solitamente un problema di applicazione, comando, probe, permessi o memoria. Inizia con questa suddivisione e il percorso di risoluzione dei problemi diventa molto più breve.

Comprensione degli Stati dei Pod: Pending vs. CrashLoopBackOff

Prima di addentrarci nella risoluzione dei problemi, è essenziale capire cosa significano questi due stati.

Stato del Pod: Pending

Un Pod nello stato Pending significa che Kubernetes ha accettato l'oggetto Pod, ma non è ancora passato completamente a uno stato di contenitore in esecuzione. A volte non è stato schedulato su un nodo. A volte ha un nodo assegnato, ma il pull dell'immagine, l'attacco del volume o la configurazione del sandbox non sono stati completati.

Stato del Pod: CrashLoopBackOff

Un Pod nello stato CrashLoopBackOff significa che un contenitore all'interno del Pod si avvia, si arresta in modo anomalo e si riavvia ripetutamente. Kubernetes implementa un ritardo di back-off esponenziale tra i riavvii per evitare di sovraccaricare il nodo. Questo stato punta quasi sempre a un problema con l'applicazione in esecuzione all'interno del contenitore stesso o con il suo ambiente immediato.

Un caso sottile: un contenitore può uscire con codice 0 ed entrare comunque in un ciclo di riavvio se il carico di lavoro dovrebbe essere un server a lunga esecuzione. Questo accade spesso quando un Deployment esegue per errore un comando monouso, come uno script di migrazione o un comando shell che termina immediatamente.

Risoluzione dei Problemi dei Pod in Stato Pending

Quando un Pod è Pending, il primo posto da guardare è lo scheduler e il nodo su cui sta cercando di posizionarsi. Ecco le cause comuni e i passaggi diagnostici.

1. Risorse Insufficienti sui Nodi

Uno dei motivi più frequenti per cui un Pod è Pending è che nessun nodo nel cluster ha risorse disponibili sufficienti (CPU, memoria) per soddisfare le requests del Pod. Lo scheduler non riesce a trovare un nodo adatto.

Passaggi Diagnostici:

Descrivi il Pod: Il comando kubectl describe pod è il tuo migliore amico qui. Spesso mostrerà eventi che dettagliano perché il Pod non può essere schedulato.
```
kubectl describe pod <nome-pod> -n <namespace>
```
Cerca eventi come "FailedScheduling" e messaggi come "0/3 nodes are available: 3 Insufficient cpu" o "memory".
Controlla le Risorse dei Nodi: Visualizza l'utilizzo e la capacità attuali delle risorse dei tuoi nodi.
```
kubectl get nodes
kubectl top nodes # (richiede metrics-server)
```

Soluzione:

Aumenta la Capacità del Cluster: Aggiungi più nodi al tuo cluster Kubernetes.
Regola le Richieste di Risorse del Pod: Riduci le requests per CPU e memoria nel manifest del tuo Pod se sono impostate troppo alte.
```
resources:
  requests:
    memory: "128Mi"
    cpu: "250m"
```
Espelli Altri Pod: Espelli manualmente i Pod a priorità più bassa dai nodi per liberare risorse (usa con cautela).

2. Errori di Pull dell'Immagine

Se Kubernetes può schedulare il Pod su un nodo, ma il nodo non riesce a fare il pull dell'immagine del contenitore, il Pod rimarrà Pending.

Cause Comuni:

Nome/Tag dell'Immagine Errato: Errori di battitura nel nome dell'immagine o utilizzo di un tag inesistente.
Autenticazione del Registro Privato: ImagePullSecrets mancanti o errati per registri privati.
Problemi di Rete: Il nodo non riesce a raggiungere il registro delle immagini.

Passaggi Diagnostici:

Descrivi il Pod: Ancora una volta, kubectl describe pod è fondamentale. Cerca eventi come "Failed" o "ErrImagePull" o "ImagePullBackOff".
```
kubectl describe pod <nome-pod> -n <namespace>
```
Esempio di evento di output: Failed to pull image "my-private-registry/my-app:v1.0": rpc error: code = Unknown desc = Error response from daemon: pull access denied for my-private-registry/my-app, repository does not exist or may require 'docker login'
Controlla ImagePullSecrets: Verifica che imagePullSecrets siano configurati correttamente nel tuo Pod o ServiceAccount.
```
kubectl get secret <tuo-image-pull-secret> -o yaml -n <namespace>
```

Soluzione:

Correggi Nome/Tag dell'Immagine: Ricontrolla il nome e il tag dell'immagine nel manifest del tuo deployment.

Configura ImagePullSecrets: Assicurati di aver creato un segreto docker-registry e di averlo collegato al tuo Pod o ServiceAccount.

kubectl create secret docker-registry my-registry-secret \
  --docker-server=your-registry.com \
  --docker-username=your-username \
  --docker-password=your-password \
  --docker-email=your-email -n <namespace>

Quindi, aggiungilo alla specifica del tuo Pod:

spec:
  imagePullSecrets:
  - name: my-registry-secret
  containers:
  ...

Connettività di Rete: Verifica la connettività di rete dal nodo al registro delle immagini.

Se stai utilizzando un registro privato, controlla anche il ServiceAccount. Molti team collegano imagePullSecrets al ServiceAccount predefinito del namespace invece che a ogni Deployment:

kubectl get serviceaccount default -n <namespace> -o yaml

Se il segreto esiste ma il pull fallisce ancora, conferma che il nome host del registro nel segreto corrisponda esattamente al nome host nel riferimento dell'immagine. registry.example.com/app:v1 e https://registry.example.com/app:v1 non sono lo stesso riferimento.

3. Problemi Relativi ai Volumi

Se il tuo Pod richiede un PersistentVolumeClaim (PVC) e il corrispondente PersistentVolume (PV) non può essere provisionato o associato, il Pod rimarrà Pending.

Passaggi Diagnostici:

Descrivi il Pod: Cerca eventi relativi ai volumi.
```
kubectl describe pod <nome-pod> -n <namespace>
```
Gli eventi potrebbero mostrare FailedAttachVolume, FailedMount o messaggi simili.
Controlla lo Stato di PVC e PV: Ispeziona lo stato del PVC e del PV.
```
kubectl get pvc <nome-pvc> -n <namespace>
kubectl get pv
```
Cerca PVC bloccati in Pending o PV non associati.

Soluzione:

Assicurati che StorageClass esista: Assicurati che una StorageClass sia definita e disponibile, specialmente se si utilizza il provisioning dinamico.
Controlla la Disponibilità del PV: Se si utilizza il provisioning statico, assicurati che il PV esista e corrisponda ai criteri del PVC.
Verifica le Modalità di Accesso: Assicurati che le modalità di accesso (ad es., ReadWriteOnce, ReadWriteMany) siano compatibili.

Controlla anche se il pod è schedulato in una zona in cui il volume può essere attaccato. Nei cluster cloud, un disco creato in una zona di disponibilità potrebbe non essere attaccato a un nodo in un'altra. L'evento di solito menziona l'affinità del nodo del volume o un errore di attacco. In tal caso, la soluzione potrebbe essere vincoli di scheduling, una StorageClass diversa o la ricreazione del volume nella zona corretta.

4. Taints, Tolerations e Node Selector

Un pod può rimanere Pending anche quando il cluster ha molta CPU e memoria. Lo scheduler deve anche rispettare le regole di posizionamento.

Esempi comuni:

Il pod ha un nodeSelector che non corrisponde a nessun nodo.
Il pod richiede un'affinità del nodo troppo restrittiva.
Gli unici nodi corrispondenti hanno taint e il pod non ha una toleration corrispondente.
Il namespace ha una quota che blocca le risorse richieste.

Controlla prima gli eventi di scheduling:

kubectl describe pod <nome-pod> -n <namespace>

Quindi confronta le regole di posizionamento del pod con le etichette dei nodi:

kubectl get pod <nome-pod> -n <namespace> -o yaml
kubectl get nodes --show-labels
kubectl describe node <nome-nodo>

Se l'evento dice che un taint non è stato tollerato, programma il pod da qualche altra parte o aggiungi una toleration solo se quel carico di lavoro appartiene veramente a quei nodi. Non tollerare ciecamente ogni taint. I taint spesso proteggono nodi speciali, nodi GPU, nodi infrastrutturali o nodi sotto pressione.

Risoluzione dei Problemi dei Pod in Stato CrashLoopBackOff

Uno stato CrashLoopBackOff indica un problema a livello di applicazione. Il contenitore si è avviato con successo ma poi è uscito con un errore, spingendo Kubernetes a riavviarlo ripetutamente.

1. Errori dell'Applicazione

La causa più comune è che l'applicazione stessa non riesce ad avviarsi o incontra un errore fatale poco dopo l'avvio.

Cause Comuni:

Dipendenze/Configurazione Mancanti: L'applicazione non riesce a trovare file di configurazione critici, variabili d'ambiente o servizi esterni da cui dipende.
Comando/Argomenti Errati: Il command o args specificati nella specifica del contenitore sono errati o portano a un'uscita immediata.
Errori Logici dell'Applicazione: Bug nel codice dell'applicazione che causano un crash all'avvio.

Passaggi Diagnostici:

Visualizza i Log del Pod: Questo è il passaggio più critico. I log mostreranno spesso il messaggio di errore esatto che ha causato il crash dell'applicazione.
```
kubectl logs <nome-pod> -n <namespace>
```
Se il Pod si arresta in modo anomalo ripetutamente, i log potrebbero mostrare l'output del tentativo fallito più recente. Per vedere i log di un'istanza precedente di un contenitore in crash, usa il flag -p (precedente):
```
kubectl logs <nome-pod> -p -n <namespace>
```
Descrivi il Pod: Cerca Restart Count nella sezione Containers, che indica quante volte il contenitore è andato in crash. Controlla anche Last State per Exit Code.
```
kubectl describe pod <nome-pod> -n <namespace>
```
Un codice di uscita 0 di solito significa un arresto normale, ma qualsiasi codice di uscita diverso da zero significa un errore. I codici di uscita comuni diversi da zero includono 1 (errore generale), 137 (SIGKILL, spesso OOMKilled), 139 (SIGSEGV, segmentation fault).

Soluzione:

Rivedi i Log dell'Applicazione: In base ai log, esegui il debug del codice o della configurazione dell'applicazione. Assicurati che tutte le variabili d'ambiente, i ConfigMap e i Secret richiesti siano montati/iniettati correttamente.
Testa Localmente: Prova a eseguire l'immagine del contenitore localmente con le stesse variabili d'ambiente e comandi per riprodurre e risolvere il problema.

Se il pod ha più contenitori, specifica sempre il nome del contenitore:

kubectl logs <nome-pod> -c <nome-contenitore> -n <namespace>
kubectl logs <nome-pod> -c <nome-contenitore> -p -n <namespace>

Senza -c, potresti leggere i log del sidecar mentre l'app principale è quella che va in crash.

2. Liveness e Readiness Probe che Falliscono

Kubernetes utilizza i probe Liveness e Readiness per determinare lo stato di salute e la disponibilità della tua applicazione. Se un liveness probe fallisce continuamente, Kubernetes riavvierà il contenitore, portando a CrashLoopBackOff.

Passaggi Diagnostici:

Descrivi il Pod: Controlla le definizioni dei probe Liveness e Readiness e il loro Last State nella sezione Containers.
```
kubectl describe pod <nome-pod> -n <namespace>
```
Cerca messaggi che indicano fallimenti dei probe, come "Liveness probe failed: HTTP probe failed with statuscode: 500".
Rivedi i Log dell'Applicazione: A volte i log dell'applicazione forniranno il contesto per cui l'endpoint del probe sta fallendo.

Soluzione:

Regola la Configurazione del Probe: Correggi path, port, command, initialDelaySeconds, periodSeconds o failureThreshold del probe.
Assicura la Salute dell'Endpoint del Probe: Verifica che l'endpoint dell'applicazione preso di mira dal probe sia effettivamente sano e risponda come previsto. L'applicazione potrebbe impiegare troppo tempo per avviarsi, richiedendo un initialDelaySeconds più grande.

Per le applicazioni ad avvio lento, considera un startupProbe. Dà all'applicazione più tempo per inizializzarsi prima che il liveness probe inizi a giudicarla. Questo è più pulito che impostare un enorme initialDelaySeconds di liveness per ogni riavvio.

3. Limiti di Risorsa Superati

Se un contenitore tenta costantemente di utilizzare più memoria del suo memory.limit o viene limitato dalla CPU a causa del superamento del suo cpu.limit, il kernel potrebbe terminare il processo, spesso con un evento OOMKilled (Out Of Memory Killed).

Passaggi Diagnostici:

Descrivi il Pod: Cerca OOMKilled nella sezione Last State o Events. Un Exit Code: 137 spesso indica un evento OOMKilled.
```
kubectl describe pod <nome-pod> -n <namespace>
```
Controlla kubectl top: Se metrics-server è installato, usa kubectl top pod per vedere l'utilizzo effettivo delle risorse dei tuoi Pod.
```
kubectl top pod <nome-pod> -n <namespace>
```

Soluzione:

Aumenta i Limiti di Risorsa: Se la tua applicazione necessita genuinamente di più risorse, aumenta i limits di memory e/o cpu nel manifest del tuo Pod. Questo potrebbe richiedere più capacità sui tuoi nodi.
```
resources:
  requests:
    memory: "256Mi"
    cpu: "500m"
  limits:
    memory: "512Mi" # Aumenta questo
    cpu: "1000m"   # Aumenta questo
```
Ottimizza l'Applicazione: Profila la tua applicazione per identificare e ridurre il suo consumo di risorse.

4. Problemi di Permessi

I contenitori potrebbero andare in crash se non hanno i permessi necessari per accedere a file, directory o risorse di rete di cui hanno bisogno.

Passaggi Diagnostici:

Rivedi i Log: I log dell'applicazione potrebbero mostrare errori di permesso negato (EACCES).
Descrivi il Pod: Controlla il ServiceAccount in uso e le eventuali impostazioni securityContext montate.

Soluzione:

Regola securityContext: Imposta runAsUser, fsGroup o allowPrivilegeEscalation come necessario.
Permessi del ServiceAccount: Assicurati che il ServiceAccount associato al Pod abbia i Roles e ClusterRoles necessari associati tramite RoleBindings e ClusterRoleBindings.
Permessi del Volume: Assicurati che i volumi montati (ad es., emptyDir, hostPath, ConfigMap, Secret) abbiano i permessi corretti per l'utente del contenitore.

Un Albero Decisionale Rapido

Quando qualcuno dice "il pod è rotto", esegui questi in ordine:

kubectl get pod <nome-pod> -n <namespace> -o wide
kubectl describe pod <nome-pod> -n <namespace>
kubectl logs <nome-pod> -n <namespace> --all-containers=true --tail=100
kubectl logs <nome-pod> -n <namespace> --all-containers=true -p --tail=100

Poi dirama:

Se non c'è nessun nodo in kubectl get pod -o wide, concentrati sullo scheduling: requests, taints, affinity, quota e disponibilità del nodo.
Se c'è un nodo ma l'evento menziona il pull dell'immagine, concentrati su nome dell'immagine, tag, autenticazione del registro e accesso di rete dal nodo al registro.
Se l'evento menziona mount o attach, concentrati su PVC, PV, StorageClass, modalità di accesso e posizionamento della zona.
Se il pod si avvia e poi si riavvia, concentrati su log, codice di uscita, probe, comando/args, configurazione, secret e limiti di memoria.

Questo ordine evita un errore comune: leggere i log dell'applicazione per un pod che non ha mai effettivamente avviato un contenitore applicativo.

Leggere i Codici di Uscita Senza Reagire in Modo Eccessivo

I codici di uscita sono indizi, non spiegazioni complete.

1 di solito significa che l'applicazione ha restituito un errore generale. I log sono più importanti del numero.
2 può indicare errori di utilizzo della riga di comando in molti programmi.
126 spesso significa che il comando esiste ma non può essere eseguito.
127 spesso significa che il comando non è stato trovato.
137 appare comunemente quando il processo riceve SIGKILL; in Kubernetes questo è spesso, ma non sempre, collegato a OOMKilled.
143 significa che il processo ha ricevuto SIGTERM, che può accadere durante la terminazione normale.

Se il codice di uscita è 137, controlla Last State del pod e gli eventi prima di presumere una perdita di memoria. Un drenaggio del nodo, un'evizione o un kill manuale possono anche terminare un contenitore.

Passaggi Diagnostici Generali e Strumenti

Ecco un rapido elenco di controllo dei comandi da eseguire quando si affrontano problemi con i Pod:

Ottieni una Panoramica Rapida: Controlla lo stato dei tuoi Pod.

kubectl get pods -n <namespace>
kubectl get pods -n <namespace> -o wide

Informazioni Dettagliate sul Pod: Il comando più cruciale per comprendere eventi, stati e condizioni del Pod.
```
kubectl describe pod <nome-pod> -n <namespace>
```

Log del Contenitore: Vedi cosa sta riportando la tua applicazione.

kubectl logs <nome-pod> -n <namespace>
kubectl logs <nome-pod> -p -n <namespace> # Istanza precedente
kubectl logs <nome-pod> -f -n <namespace> # Segui i log

Eventi a Livello di Cluster: A volte il problema non è con un Pod specifico ma con un evento a livello di cluster (ad es., pressione sul nodo).
```
kubectl get events -n <namespace>
```
Debug Interattivo: Se il tuo contenitore si avvia ma si arresta rapidamente, potresti essere in grado di eseguire exec al suo interno per un breve momento o in un contenitore di debug separato se configurato.
```
kubectl exec -it <nome-pod> -n <namespace> -- bash
```
(Nota: Funziona solo se il contenitore rimane attivo abbastanza a lungo per connettersi.)

Best Practice per Evitare Problemi con i Pod

Prevenire è meglio che curare. Seguire queste best practice può ridurre significativamente gli incidenti Pending e CrashLoopBackOff:

Imposta Richieste e Limiti di Risorsa Realistici: Inizia con requests e limits ragionevoli, poi perfezionali in base alla profilazione e al monitoraggio dell'applicazione.
Usa Tag di Immagine Specifici: Evita i tag latest in produzione. Usa tag immutabili (ad es., v1.2.3, commit-sha) per la riproducibilità.
Implementa Probe Robuste: Configura probe liveness e readiness che riflettano accuratamente lo stato di salute della tua applicazione. Tieni conto dei tempi di avvio con initialDelaySeconds.
Registrazione e Monitoraggio Centralizzati: Usa strumenti come Prometheus, Grafana, stack ELK o servizi di logging nativi del cloud per raccogliere e analizzare log e metriche dei Pod.
Controllo di Versione per i Manifest: Archivia i tuoi manifest Kubernetes in un sistema di controllo di versione (ad es., Git) per tracciare le modifiche e facilitare i rollback.
Test Approfonditi: Testa le tue immagini dei contenitori e i deployment Kubernetes in ambienti di sviluppo e staging prima di distribuirli in produzione.
Arresti Graduali: Assicurati che le tue applicazioni gestiscano i segnali SIGTERM per arresti graduali, permettendo loro di rilasciare le risorse prima della terminazione.

Cosa Di Solito Risolve Più Velocemente

Per Pending, kubectl describe pod è di solito la via più veloce perché gli eventi dello scheduler e del kubelet spiegano cosa Kubernetes non ha potuto fare. Per CrashLoopBackOff, i log precedenti sono di solito la via più veloce perché il contenitore corrente potrebbe essere troppo nuovo per mostrare il crash che ha causato il ciclo.

Dopo aver risolto il problema immediato, cerca il passaggio di prevenzione: requests della giusta dimensione, tag di immagine migliori, uno startup probe, un controllo del secret mancante in CI o un runbook più chiaro. Il miglior incidente del pod è quello che diventa più facile da riconoscere la prossima volta.