Padroneggiare `kubectl logs` e `describe` per un Debugging Efficiente dei Pod

Il debugging delle applicazioni in un ambiente distribuito come Kubernetes può essere impegnativo. Quando un pod non si avvia, entra in un ciclo di riavvio o mostra comportamenti imprevisti, i due strumenti più critici nella cassetta degli attrezzi di un operatore Kubernetes sono kubectl describe e kubectl logs.

Questi comandi forniscono visualizzazioni diverse, ma complementari, dello stato e della cronologia di un Pod Kubernetes. kubectl describe fornisce i metadati, lo stato, le variabili d'ambiente del Pod e, soprattutto, una cronologia degli eventi di sistema. kubectl logs fornisce i flussi di output standard (stdout) e di errore standard (stderr) generati dall'applicazione containerizzata stessa.

Padroneggiare i flag e le tecniche associate a questi comandi è essenziale per diagnosticare e risolvere rapidamente i problemi, migliorando significativamente l'efficienza generale di risoluzione dei problemi del cluster.

Il Flusso di Lavoro di Debug del Pod in Tre Passaggi

Prima di addentrarsi nei comandi, è utile comprendere il tipico flusso di lavoro di debugging:

Verifica dello Stato: Utilizzare kubectl get pods per identificare lo stato di fallimento (Pending, CrashLoopBackOff, ImagePullBackOff, ecc.).
Ottenere Contesto ed Eventi: Utilizzare kubectl describe pod per capire perché si è verificata la transizione di stato (ad esempio, lo scheduler ha fallito, la sonda di Liveness è fallita, il volume non è stato montato).
Ispezionare l'Output dell'Applicazione: Utilizzare kubectl logs per esaminare il comportamento runtime dell'applicazione (ad esempio, errori di configurazione, problemi di connessione al database, stack trace).

1. `kubectl describe`: Lo Strumento di Triage di Sistema

kubectl describe è il primo comando da eseguire quando un Pod non funziona correttamente. Non mostra l'output dell'applicazione, ma fornisce i metadati e la cronologia critici che Kubernetes stesso ha registrato sul Pod.

Utilizzo Base

L'utilizzo fondamentale richiede solo il nome del Pod:

kubectl describe pod mio-app-fallimentare-xyz789

Sezioni Chiave nell'Output

Quando si esamina l'output di describe, concentrarsi su queste sezioni critiche:

A. Stato e Condizione

Osservare il campo Status in alto, e poi rivedere gli stati dei singoli container all'interno del Pod. Questo indica se il container è Running (In Esecuzione), Waiting (In Attesa) o Terminated (Terminato) e fornisce il motivo di tale stato.

Campo	Stato/Motivo Comune	Significato
`Status`	`Pending`	Il Pod è in attesa di essere schedulato o mancano risorse.
`Reason`	`ContainerCreating`	Il runtime del container sta scaricando l'immagine o eseguendo la configurazione.
`State`	`Waiting` / `Reason: CrashLoopBackOff`	Il container è stato avviato ed è terminato ripetutamente.
`State`	`Terminated` / `Exit Code`	Il container ha terminato l'esecuzione. I codici di uscita diversi da zero indicano solitamente errori.

B. Configurazione del Container

Questa sezione verifica che le variabili d'ambiente, le richieste/limiti di risorse, i mount dei volumi e le sonde di Liveness/Readiness siano definiti correttamente, corrispondendo al manifest applicato.

C. La Sezione `Events` (Cruciale)

La sezione Events, situata in fondo all'output, è forse la parte più preziosa. Fornisce un log cronologico di ciò che il piano di controllo di Kubernetes ha fatto per e al Pod, inclusi avvisi ed errori.

Errori Comuni Rivelati da Events:

Problemi di Scheduling: Warning FailedScheduling: Indica che lo scheduler non è riuscito a trovare un nodo adatto (ad esempio, a causa di vincoli di risorse, taint dei nodi o regole di affinità).
Errori di Pull dell'Immagine: Warning Failed: ImagePullBackOff: Indica che il nome dell'immagine non è corretto, il tag non esiste o Kubernetes non dispone delle credenziali per scaricare da un registro privato.
Errori dei Volumi: Warning FailedAttachVolume: Indica problemi nel collegamento dello storage esterno.

Suggerimento: Se la sezione Events è pulita, il problema è solitamente correlato all'applicazione (crash runtime, fallimento dell'inizializzazione, errore di configurazione), indirizzandoti a utilizzare kubectl logs successivamente.

2. `kubectl logs`: Ispezionare l'Output dell'Applicazione

Se describe mostra che il Pod è stato schedulato con successo e i container hanno tentato di avviarsi, il passo successivo è controllare i flussi di output standard utilizzando kubectl logs.

Recupero Base dei Log e Streaming in Tempo Reale

Per visualizzare i log correnti per il container principale in un Pod:

# Recupera tutti i log fino al momento attuale
kubectl logs mio-app-fallimentare-xyz789

# Trasmette i log in tempo reale (utile per monitorare l'avvio)
kubectl logs -f mio-app-fallimentare-xyz789

Gestione di Pod Multi-Container

Per i pod che utilizzano il modello Sidecar o altri design multi-container, è necessario specificare i log di quale container si desidera visualizzare utilizzando il flag -c o --container.

# Visualizza i log per il container 'sidecar-proxy' all'interno del Pod
kubectl logs mio-pod-multi-container -c sidecar-proxy

# Trasmette i log per il container dell'applicazione principale
kubectl logs -f mio-pod-multi-container -c main-app

Debug dei Container in Riavvio (`--previous`)

Uno degli scenari di debugging più comuni è lo stato CrashLoopBackOff. Quando un container si riavvia, kubectl logs mostra solo l'output del tentativo corrente (fallito), che spesso contiene solo il messaggio di avvio prima del crash.

Per visualizzare i log dell'istanza terminata precedente—che contiene l'errore effettivo che ha causato la terminazione—utilizzare il flag --previous (-p):

# Visualizza i log dalla precedente istanza di container andata in crash
kubectl logs mio-pod-crashloop --previous

# Combina con la specifica del container se necessario
kubectl logs mio-pod-crashloop -c worker --previous

Limitare l'Output

Per i log ad alto volume, recuperare l'intera cronologia può essere lento o eccessivo. Utilizzare --tail per limitare l'output alle ultime N righe.

# Mostra solo le ultime 50 righe dei log del container
kubectl logs mio-app-traffico-elevato --tail=50

3. Combinare Tecniche per una Diagnosi Avanzata

Il debugging efficace spesso comporta il passaggio rapido tra describe e i comandi specifici di logs.

Caso di Studio: Diagnosi del Fallimento della Liveness Probe

Immagina un Pod bloccato su Running ma che si riavvia occasionalmente, causando interruzioni.

Passo 1: Controllare describe per la vista di sistema.

kubectl describe pod web-server-dpl-abc

L'output mostra nella sezione Eventi:

Tipo     Motivo      Età   Da                 Messaggio
----     ------      ----  ----               -------
Warning  Unhealthy   2s    kubelet, node-a01  Liveness probe failed: HTTP GET http://10.42.0.5:8080/health failed: 503 Service Unavailable

Conclusione dal Passo 1: Il container è in esecuzione, ma la Liveness probe sta fallendo con un errore 503, causando il riavvio del container da parte di Kubernetes.

Passo 2: Controllare logs per il contesto dell'applicazione.

Ora, indaga perché l'applicazione restituisce uno stato 503, che è un fallimento a livello di applicazione.

kubectl logs web-server-dpl-abc --tail=200

L'output dei log rivela:

2023-10-26 14:01:15 ERROR Database connection failure: Timeout connecting to DB instance 192.168.1.10

Conclusione Finale: Il Pod si sta riavviando a causa di una Liveness probe fallita, e la probe sta fallendo perché l'applicazione non riesce a connettersi al database. Il problema è di rete esterna o di configurazione del database, non del container stesso.

Best Practice e Avvertenze

Pratica	Comando	Motivazione
Controllare sempre i log precedenti	`kubectl logs --previous`	Necessario per diagnosticare `CrashLoopBackOff`. L'errore critico è quasi sempre nella corsa precedente.
Specificare i container	`kubectl logs -c <nome>`	Evita ambiguità nei Pod multi-container e impedisce di recuperare i log da sidecar non intenzionali.
Usare etichette per operazioni di massa	`kubectl logs -l app=frontend -f`	Consente di trasmettere simultaneamente i log da più Pod che corrispondono a un selettore (utile per gli aggiornamenti rolling).
Avvertenza: Rotazione dei Log	N/A	I nodi Kubernetes eseguono la rotazione dei log. I log più vecchi della policy di conservazione configurata del nodo (spesso pochi giorni o basata sulla dimensione) verranno eliminati e non saranno disponibili tramite `kubectl logs`. Utilizzare una soluzione di logging centralizzata esterna (ad esempio, Fluentd, Loki, Elastic Stack) per la conservazione a lungo termine.

Conclusione

kubectl describe e kubectl logs sono i comandi fondamentali indispensabili per il debugging in Kubernetes. Trattando describe come il report dello stato del sistema (concentrandosi sulla configurazione, sugli eventi e sugli errori di scheduling) e logs come lo stream di esecuzione dell'applicazione (concentrandosi sugli errori di codice e sul comportamento runtime), è possibile circoscrivere sistematicamente la causa di quasi tutti i fallimenti dei Pod, riducendo significativamente il Mean Time To Resolution (MTTR) all'interno del cluster.