Guide Troubleshooting Kubernetes

1. Diagnostic Rapide du Cluster

État global

# Vue d'ensemble du cluster
kubectl cluster-info

# État des nodes
kubectl get nodes -o wide

# Nodes avec problèmes
kubectl get nodes | grep -v " Ready"

# Détails d'un node problématique
kubectl describe node <node-name> | grep -A 20 "Conditions:"

# Ressources disponibles par node
kubectl top nodes

# Events récents du cluster
kubectl get events --all-namespaces --sort-by='.lastTimestamp' | tail -50

Composants système

# État des composants du control plane
kubectl get componentstatuses

# Pods système
kubectl get pods -n kube-system

# Pods en erreur dans kube-system
kubectl get pods -n kube-system | grep -v Running | grep -v Completed

2. Diagnostic des Pods

Trouver les pods problématiques

# Pods non Running dans tous les namespaces
kubectl get pods -A | grep -v Running | grep -v Completed

# Pods en CrashLoopBackOff
kubectl get pods -A | grep CrashLoopBackOff

# Pods en Pending
kubectl get pods -A | grep Pending

# Pods avec beaucoup de restarts
kubectl get pods -A -o wide | awk '$5 > 3 {print}'

# Pods par état
kubectl get pods -A -o jsonpath='{range .items[*]}{.status.phase}{"\n"}{end}' | sort | uniq -c

Analyser un pod spécifique

# Description complète
kubectl describe pod <pod-name> -n <namespace>

# Logs du container principal
kubectl logs <pod-name> -n <namespace>

# Logs du container précédent (après crash)
kubectl logs <pod-name> -n <namespace> --previous

# Logs d'un container spécifique (multi-container)
kubectl logs <pod-name> -n <namespace> -c <container-name>

# Suivre les logs en temps réel
kubectl logs -f <pod-name> -n <namespace>

# Logs des 100 dernières lignes
kubectl logs --tail=100 <pod-name> -n <namespace>

# Logs depuis les dernières 5 minutes
kubectl logs --since=5m <pod-name> -n <namespace>

Debug interactif

# Shell dans un pod
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh

# Shell avec bash si disponible
kubectl exec -it <pod-name> -n <namespace> -- /bin/bash

# Commande unique
kubectl exec <pod-name> -n <namespace> -- cat /app/config.yaml

# Container spécifique
kubectl exec -it <pod-name> -n <namespace> -c <container> -- /bin/sh

3. Diagnostic des Deployments

# État des deployments
kubectl get deployments -n <namespace>

# Historique des rollouts
kubectl rollout history deployment/<name> -n <namespace>

# État du rollout en cours
kubectl rollout status deployment/<name> -n <namespace>

# Détails des ReplicaSets
kubectl get rs -n <namespace>

# Raison d'un déploiement bloqué
kubectl describe deployment <name> -n <namespace> | grep -A 10 "Conditions:"

# Rollback au déploiement précédent
kubectl rollout undo deployment/<name> -n <namespace>

# Rollback à une révision spécifique
kubectl rollout undo deployment/<name> -n <namespace> --to-revision=2

4. Diagnostic Réseau

Services

# Liste des services
kubectl get svc -n <namespace>

# Endpoints d'un service (pods derrière)
kubectl get endpoints <service-name> -n <namespace>

# Service sans endpoints (problème!)
kubectl get endpoints -n <namespace> | awk '$2 == "<none>"'

# Test de résolution DNS interne
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup <service-name>.<namespace>.svc.cluster.local

# Test de connectivité
kubectl run -it --rm debug --image=busybox --restart=Never -- wget -qO- http://<service-name>.<namespace>:80

Ingress

# Liste des ingress
kubectl get ingress -n <namespace>

# Détails d'un ingress
kubectl describe ingress <name> -n <namespace>

# Logs du controller ingress
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx --tail=100

Network Policies

# Lister les network policies
kubectl get networkpolicies -n <namespace>

# Détails (règles appliquées)
kubectl describe networkpolicy <name> -n <namespace>

5. Diagnostic Stockage

# PersistentVolumes
kubectl get pv

# PersistentVolumeClaims
kubectl get pvc -n <namespace>

# PVC en Pending (problème de binding)
kubectl get pvc -A | grep Pending

# Détails d'un PVC
kubectl describe pvc <name> -n <namespace>

# StorageClasses disponibles
kubectl get storageclass

# Utilisation disque des pods
kubectl exec <pod-name> -n <namespace> -- df -h

6. Diagnostic Ressources

CPU et Mémoire

# Utilisation par pod
kubectl top pods -n <namespace>

# Utilisation par node
kubectl top nodes

# Pods par consommation CPU (tri)
kubectl top pods -A --sort-by=cpu | head -20

# Pods par consommation mémoire
kubectl top pods -A --sort-by=memory | head -20

# Requests/Limits d'un pod
kubectl get pod <name> -n <namespace> -o jsonpath='{.spec.containers[*].resources}'

Quotas

# ResourceQuotas
kubectl get resourcequota -n <namespace>

# Utilisation du quota
kubectl describe resourcequota -n <namespace>

# LimitRanges
kubectl get limitrange -n <namespace>

7. Diagnostic RBAC

# Vérifier les permissions d'un user
kubectl auth can-i list pods --as=<user>

# Vérifier les permissions d'un ServiceAccount
kubectl auth can-i list secrets --as=system:serviceaccount:<namespace>:<sa-name>

# Lister toutes les permissions
kubectl auth can-i --list --as=system:serviceaccount:<namespace>:<sa-name>

# ClusterRoles
kubectl get clusterroles | grep -v system:

# RoleBindings d'un namespace
kubectl get rolebindings -n <namespace>

# Qui a accès à quoi
kubectl get clusterrolebindings -o wide | grep -E "(admin|edit|view)"

8. Diagnostic des Events

# Events d'un namespace (triés par date)
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

# Events de type Warning uniquement
kubectl get events -n <namespace> --field-selector type=Warning

# Events d'un pod spécifique
kubectl get events -n <namespace> --field-selector involvedObject.name=<pod-name>

# Events récents (dernière heure)
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -50

# Watch des events en temps réel
kubectl get events -n <namespace> -w

9. Commandes de Debug Avancées

Debug avec un pod éphémère

# Attacher un container de debug à un pod
kubectl debug <pod-name> -it --image=busybox --target=<container-name> -n <namespace>

# Créer une copie du pod pour debug
kubectl debug <pod-name> -it --copy-to=debug-pod --image=ubuntu -n <namespace>

# Debug d'un node
kubectl debug node/<node-name> -it --image=ubuntu

Analyse JSON avancée

# Extraire les images de tous les pods
kubectl get pods -A -o jsonpath='{range .items[*]}{.spec.containers[*].image}{"\n"}{end}' | sort -u

# Pods sans limits définis
kubectl get pods -A -o json | jq '.items[] | select(.spec.containers[].resources.limits == null) | .metadata.name'

# Pods avec restart count > 0
kubectl get pods -A -o json | jq '.items[] | select(.status.containerStatuses[].restartCount > 0) | {name: .metadata.name, restarts: .status.containerStatuses[].restartCount}'

10. Scripts de Diagnostic

Script de santé cluster

#!/bin/bash
echo "=== CLUSTER HEALTH CHECK ==="
echo ""

echo "📊 Nodes Status:"
kubectl get nodes -o wide
echo ""

echo "⚠️ Problematic Pods:"
kubectl get pods -A | grep -v Running | grep -v Completed | head -20
echo ""

echo "🔥 High Restart Pods:"
kubectl get pods -A -o wide | awk '$5 > 3 {print}' | head -10
echo ""

echo "💾 PVC Issues:"
kubectl get pvc -A | grep -v Bound
echo ""

echo "📝 Recent Warnings:"
kubectl get events -A --field-selector type=Warning --sort-by='.lastTimestamp' | tail -10
echo ""

echo "💻 Resource Usage:"
kubectl top nodes 2>/dev/null || echo "Metrics server not available"

Script diagnostic pod

#!/bin/bash
POD=$1
NS=${2:-default}

if [ -z "$POD" ]; then
  echo "Usage: $0 <pod-name> [namespace]"
  exit 1
fi

echo "=== POD DIAGNOSTIC: $POD in $NS ==="
echo ""

echo "📋 Pod Status:"
kubectl get pod $POD -n $NS -o wide
echo ""

echo "📝 Pod Description:"
kubectl describe pod $POD -n $NS | grep -A 30 "Events:"
echo ""

echo "📊 Resource Usage:"
kubectl top pod $POD -n $NS 2>/dev/null || echo "Metrics not available"
echo ""

echo "📜 Recent Logs:"
kubectl logs $POD -n $NS --tail=50 2>/dev/null || echo "No logs available"

Aide-Mémoire des Codes d'Erreur

Ces commandes fonctionnent avec kubectl 1.28+. Testées sur clusters EKS, GKE et on-premise.