Debug di Deployment Falliti: Identificazione degli Errori Comuni di YAML e Configurazione

I fallimenti dei deployment Kubernetes di solito si manifestano con pod bloccati in stato Pending, ImagePullBackOff, CrashLoopBackOff o con zero repliche disponibili. La causa è spesso visibile negli eventi, ma è necessario ispezionare Deployment, ReplicaSet e Pod nell'ordine corretto.

Questa guida illustra i controlli che di solito individuano errori YAML, problemi di pull delle immagini, probe errati, vincoli di risorse e regole di scheduling che impediscono al deployment di diventare sano.

I Primi Passi: Controllo dello Stato del Deployment e degli Eventi

Quando un deployment fallisce, i primi passi diagnostici dovrebbero sempre includere il controllo della risorsa principale stessa e degli eventi associati ai suoi ReplicaSet e Pod gestiti. Questo fornisce la visione di più alto livello di ciò che Kubernetes sta tentando di fare e perché sta fallendo.

1. Ispezione dello Stato del Deployment

Usa kubectl get deployments per vedere lo stato generale. Osserva in particolare le colonne READY, UP-TO-DATE e AVAILABLE. Una discrepanza qui indica un problema con i Pod sottostanti.

kubectl get deployments <nome-deployment>

Se lo stato del deployment mostra poche o zero repliche pronte, procedi a controllare il ReplicaSet.

2. Revisione degli Eventi di ReplicaSet e Pod

I ReplicaSet gestiscono il numero desiderato di Pod. Se il deployment fallisce, il ReplicaSet è di solito la fonte della cascata di errori. Usa il comando describe sul ReplicaSet, che di solito è denominato <nome-deployment>-<hash>:

kubectl describe rs <nome-replicaset>

Fondamentalmente, esamina la sezione Events in fondo all'output. Questa sezione dettaglia le azioni recenti, inclusi tentativi di scheduling, fallimenti di pull delle immagini e problemi di montaggio dei volumi. Questi eventi sono spesso la prova decisiva.

Infine, controlla i Pod stessi, poiché riportano il fallimento immediato:

kubectl get pods -l app=<etichetta-tua-app>
kubectl describe pod <nome-pod>

Cerca i campi State e Reason nella descrizione del pod. Le ragioni comuni includono ImagePullBackOff, ErrImagePull, CrashLoopBackOff e Pending.

Errori Comuni di Configurazione nei Manifest YAML

Le configurazioni errate nei tuoi file YAML sono la causa più frequente di fallimenti dei deployment. Questi errori possono variare da semplici errori di indentazione a problemi strutturali complessi.

1. Errori di Sintassi e Struttura YAML

Le API Kubernetes sono estremamente sensibili alla corretta sintassi YAML (indentazione, spaziatura e tipi di dati). Se lo YAML non è valido, kubectl apply spesso fallirà immediatamente, dichiarando di non poter analizzare il file.

Buona Pratica: Usa un Linter Valida sempre la sintassi YAML prima di applicare. Strumenti come yamllint o il supporto IDE integrato possono individuare immediatamente errori di sintassi di base.

Esempio di un errore strutturale comune: Mappatura o indentazione errata.

# ERRATO: containers appartiene a spec.template.spec, non direttamente a spec.template
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mia-app
spec:
  template:
    metadata:
      labels:
        app: mia-app
    containers:
      - name: mia-app
        image: myregistry/miaapp:v1

Posizionamento corretto:

spec:
  template:
    metadata:
      labels:
        app: mia-app
    spec:
      containers:
        - name: mia-app
          image: myregistry/miaapp:v1
          ports:
            - containerPort: 8080

2. Errori di Riferimento all'Immagine e Pull

Se i Pod entrano in stato ImagePullBackOff o ErrImagePull, il problema è relativo all'accesso all'immagine del contenitore.

Errore di Battitura nel Nome/Tag dell'Immagine: Ricontrolla l'ortografia del repository dell'immagine, del nome e del tag.
Autenticazione del Registro Privato: Se stai effettuando il pull da un registro privato, assicurati di aver creato un segreto per il pull dell'immagine e di averlo referenziato come imagePullSecrets nella specifica del Pod.

# Frammento che mostra l'uso di ImagePullSecret
spec:
  imagePullSecrets:
    - name: mio-segreto-registro
  containers:
    - name: mia-app
      image: private.example.com/mia-app:v1

3. Violazioni delle Richieste e dei Limiti delle Risorse

Se un Pod rimane in stato Pending e gli eventi menzionano risorse insufficienti, i nodi del cluster non possono soddisfare i requisiti di CPU o memoria definiti nello YAML.

Controlla i limiti specificati nel tuo manifest di deployment:

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

Passaggi di Risoluzione dei Problemi:

Usa kubectl describe nodes per vedere la capacità disponibile.
Se vedi eventi come 0/3 nodes are available: 3 Insufficient cpu, devi abbassare le requests nel tuo YAML o aggiungere più nodi al cluster.

Problemi di Configurazione Avanzati

Oltre alla sintassi di base e ai pull di immagini, configurazioni complesse che coinvolgono networking, storage e scheduling possono portare a fallimenti difficili da diagnosticare.

1. Probe Configurati Erroneamente (Liveness e Readiness)

Se un Pod passa a CrashLoopBackOff, spesso significa che il contenitore si avvia ma fallisce immediatamente un controllo, oppure si avvia ma fallisce ripetutamente il suo probe di readiness.

Probe di Liveness: Se questo fallisce ripetutamente, Kubernetes riavvia il contenitore. Controlla kubectl describe pod <nome-pod> per eventi di fallimento del probe e kubectl logs <nome-pod> --previous dopo un riavvio.
Probe di Readiness: Se questo fallisce, il Pod continua a funzionare ma viene tenuto fuori dagli endpoint del Service. Assicurati che il percorso, la porta e il codice di risposta previsto corrispondano a ciò che la tua applicazione sta effettivamente servendo.

Esempio di un errore comune del Probe di Readiness: Puntare alla porta sbagliata o aspettarsi HTTP quando l'app espone solo TCP.

2. Fallimenti di Volume e PersistentVolumeClaim (PVC)

Se i Pod sono in attesa a causa di problemi di volume, ispeziona lo stato del PVC:

kubectl get pvc <nome-pvc>

Se lo stato del PVC è Pending, significa che il cluster non ha trovato una StorageClass corrispondente o un PersistentVolume adatto a cui associarsi. Controlla gli eventi del PVC per errori di binding specifici.

3. Regole di Affinità e Anti-Affinità

Regole di scheduling complesse, come nodeAffinity o podAntiAffinity, possono inavvertitamente impedire la schedulazione di un Pod se nessun nodo soddisfa tutti i criteri. Se i Pod rimangono in Pending e gli eventi menzionano restrizioni di scheduling, rivedi queste regole.

Ad esempio, se richiedi che un Pod venga eseguito su un nodo con un'etichetta specifica (nodeSelector) che nessun nodo esistente possiede, il Pod non verrà mai schedulato.

# Esempio: Limitare il deployment a nodi etichettati 'disktype: ssd'
spec:
  nodeSelector:
    disktype: ssd
  containers:
  # ...

Suggerimento per la Risoluzione dei Problemi: Commenta temporaneamente le regole restrittive di nodeSelector o affinity. Se il Pod viene schedulato con successo, sai che il problema risiede nei criteri di selezione.

Flusso di Lavoro per il Debug

Quando ti trovi di fronte a un deployment fallito, segui questo percorso strutturato:

Stato del Deployment: kubectl get deployments -> Le repliche segnalano come pronte?
Eventi del Pod: kubectl describe pod <pod-che-fallisce> -> Controlla la sezione Events per errori immediati (ImagePull, OOMKilled, problemi di Volume).
Log del Contenitore: kubectl logs <pod-che-fallisce> -> Se il contenitore si avvia ma si blocca (CrashLoopBackOff), la logica dell'applicazione o i probe di liveness sono sospetti.
Controllo delle Risorse: Se il Pod è Pending, controlla i vincoli di risorse (Insufficient cpu/memory) o i binding di volume falliti (stato PVC).
Validazione della Configurazione: Rivedi lo YAML per indentazione, nomi di campo corretti e valori di risorse validi (requests/limits).

Lavora partendo dalle prove del cluster invece di indovinare. Controlla stato, eventi, log, risorse e struttura del manifest in quest'ordine, poi apporta la modifica YAML più piccola che corrisponde all'errore che hai trovato.