Introduction
Les problèmes réseau liés aux événements Kubernetes peuvent être ardus : les événements ne sont pas livrés, les webhooks échouent ou les journaux d'audit cessent de circuler. Ces difficultés proviennent souvent de mauvaises configurations DNS, de ports bloqués, d'erreurs de routage ou de règles de pare-feu. Ce guide propose une approche structurée pour diagnostiquer et résoudre ces problèmes à l'aide de commandes pratiques, d'extraits de configuration et d'étapes de vérification. Que vous soyez développeur gérant un cluster ou consultant DevOps accompagnant plusieurs équipes, vous apprendrez à identifier méthodiquement la cause première et à rétablir un réseau fiable pour les événements Kubernetes.
Nous commencerons par recueillir les détails de l'environnement et les versions, puis nous apporterons des modifications de configuration sûres et ciblées, nous vérifierons avec des contrôles observables, nous comprendrons les modes de défaillance courants et les étapes de récupération, et enfin nous suivrons une liste de contrôle opérationnelle réutilisable. Chaque section comprend des exemples concrets et des sorties attendues pour vous permettre d'appliquer directement les conseils.
Inventaire de l'environnement et des versions
Avant toute modification, collectez des informations sur votre cluster Kubernetes, les composants réseau et les charges de travail spécifiques liées aux événements. Cette base de référence aide à isoler le problème et évite les perturbations involontaires.
1. Versions de Kubernetes et des nœuds
Exécutez la commande suivante pour obtenir la version du cluster :
kubectl version --short
Sortie attendue (exemple) :
Client Version: v1.27.3
Server Version: v1.27.3
Notez les versions. Listez également les nœuds avec leur système d'exploitation et leur noyau :
kubectl get nodes -o wide
Exemple de sortie :
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
node-1 Ready control-plane 21d v1.27.3 192.168.1.10 <none> Ubuntu 22.04.2 LTS 5.15.0-76-generic containerd://1.6.21
node-2 Ready <none> 21d v1.27.3 192.168.1.11 <none> Ubuntu 22.04.2 LTS 5.15.0-76-generic containerd://1.6.21
2. Plugin réseau (CNI)
Confirmez quel plugin CNI est installé. Par exemple, si Calico est utilisé :
kubectl get pods -n kube-system | grep calico
Sortie attendue :
calico-node-abcde 1/1 Running 0 15d
calico-kube-controllers-12345 1/1 Running 0 15d
Notez la version du CNI à partir de l'étiquette d'image de son daemonset ou de sa configuration.
3. Configuration DNS
Kubernetes utilise CoreDNS par défaut. Vérifiez le déploiement et le service CoreDNS :
kubectl get deployment coredns -n kube-system
kubectl get service kube-dns -n kube-system
La sortie attendue montre un service avec une ClusterIP, généralement 10.96.0.10. Examinez la ConfigMap de CoreDNS pour repérer les paramètres personnalisés comme les redirecteurs ou les domaines de stub :
kubectl describe configmap coredns -n kube-system
Recherchez forward . /etc/resolv.conf ou des serveurs DNS en amont personnalisés.
4. Composants liés aux événements
Identifiez les composants qui produisent ou consomment des événements Kubernetes. Exemples courants :
kube-apiserver: contrôle la création des événements.- exportateurs d'événements (par exemple,
kubernetes-event-exporter) qui peuvent envoyer des événements vers des systèmes externes. - récepteurs de webhooks pour la livraison des événements.
Listez les pods dans les espaces de noms pertinents :
kubectl get pods -A | grep -E 'event|webhook'
Exemple :
NAMESPACE NAME READY STATUS RESTARTS AGE
monitoring event-exporter-7d4f8c5b9-xyz12 1/1 Running 0 3d
default webhook-receiver-6b9c8d7f5-abc34 1/1 Running 0 1d
5. Politiques réseau et règles de pare-feu
Recherchez les NetworkPolicies Kubernetes susceptibles de bloquer le trafic vers les destinations d'événements :
kubectl get networkpolicies -A
Passez également en revue les groupes de sécurité du fournisseur cloud ou les règles de pare-feu sur site (hors Kubernetes) le cas échéant.
6. Prérequis pour le dépannage
Assurez-vous de disposer de :
kubectlinstallé et configuré avec les droits cluster-admin ou des permissions suffisantes.- Accès aux shells des nœuds si nécessaire (ssh ou console cloud).
- Outils réseau de base :
curl,dig,nc,tcpdump,telnet(peuvent être installés s'ils manquent). - Compréhension du flux des événements : source -> serveur API -> stockage -> consommateur.
Vous avez maintenant une vision claire de l'environnement. Passons à une démarche de configuration sûre.
Démarche de configuration sûre
Lors du dépannage, évitez les modifications globales. Faites plutôt des ajustements petits et réversibles pour isoler le problème. Cette section présente une approche systématique.
1. Isoler le domaine de défaillance
Déterminez d'abord où se produit la défaillance réseau :
- L'événement n'est-il pas créé par la source ?
- L'événement n'atteint-il pas le serveur API ?
- L'événement n'est-il pas récupéré par le consommateur ?
- La livraison externe (webhook, redirecteur) échoue-t-elle ?
Utilisez les commandes suivantes pour vérifier la création et la récupération des événements :
kubectl get events --all-namespaces --sort-by='.lastTimestamp'
Si les événements sont visibles dans le cluster mais pas livrés à l'extérieur, le problème se situe probablement chez le consommateur ou sur le chemin réseau externe.
2. Vérifier la résolution DNS
Les services Kubernetes reposent sur le DNS. Testez la résolution DNS depuis un pod vers le service consommateur d'événements :
kubectl run -it --rm debug --image=busybox --restart=Never -- sh
Dans le pod, exécutez :
nslookup webhook-receiver.default.svc.cluster.local
Sortie attendue si le DNS fonctionne :
Server: 10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local
Name: webhook-receiver.default.svc.cluster.local
Address 1: 10.96.0.25 webhook-receiver.default.svc.cluster.local
Si la résolution échoue, consultez les journaux de CoreDNS :
kubectl logs -n kube-system -l k8s-app=kube-dns
Recherchez des erreurs comme SERVFAIL, NXDOMAIN ou des délais d'attente.
3. Tester la connectivité des ports
Utilisez nc (netcat) ou telnet depuis un pod de débogage pour tester la connectivité TCP vers le port du service :
kubectl run -it --rm debug --image=busybox --restart=Never -- sh
/ # nc -vz webhook-receiver.default.svc.cluster.local 8080
Sortie attendue en cas de succès :
webhook-receiver.default.svc.cluster.local (10.96.0.25:8080) open
En cas de connexion refusée ou de délai, inspectez la configuration du service et des points de terminaison :
kubectl describe service webhook-receiver
kubectl get endpoints webhook-receiver
Assurez-vous que le sélecteur du service correspond aux étiquettes des pods et que les pods sont à l'état Ready.
4. Vérifier le routage et les politiques réseau
Si des pods sur des nœuds différents ne peuvent pas communiquer, inspectez l'état du CNI. Pour Calico :
kubectl -n kube-system exec calicoctl -- calicoctl node status
Vérifiez également les NetworkPolicies susceptibles de bloquer le trafic. Par exemple, si une politique refuse la sortie depuis l'espace de noms de l'exportateur d'événements :
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: deny-external
namespace: monitoring
spec:
podSelector: {}
policyTypes:
- Egress
egress:
- to:
- namespaceSelector: {}
ports:
- protocol: TCP
port: 53
- protocol: UDP
port: 53
Cette politique n'autorise que le DNS, bloquant toute autre sortie. Pour tester, ajoutez temporairement une règle autorisant le trafic vers le service webhook, ou supprimez la politique (avec prudence). Documentez toujours la modification pour pouvoir revenir en arrière.
5. Ajuster les règles de pare-feu
Si le consommateur d'événements est hors cluster (par exemple, un webhook public), assurez-vous que les groupes de sécurité cloud ou les règles de pare-feu autorisent le trafic sortant des nœuds workers vers l'IP et le port de destination. Par exemple, sur AWS, vérifiez les règles de sortie du groupe de sécurité. Sur site, examinez iptables ou firewalld sur les nœuds :
sudo iptables -L -n | grep <destination-port>
Faites un changement ciblé : autorisez le port spécifique depuis le sous-réseau des nœuds vers la destination, enregistrez la règle précédente et appliquez.
6. Modifier la configuration de l'exportateur d'événements
Si vous utilisez kubernetes-event-exporter, ajustez sa configuration pour augmenter la verbosité ou changer de puits. Exemple d'extrait de configuration :
logLevel: debug
sinks:
webhook:
type: webhook
endpoint: http://webhook-receiver.default.svc.cluster.local:8080
Appliquez la modification via une mise à jour de ConfigMap :
kubectl edit configmap event-exporter-config -n monitoring
Puis redémarrez le pod de l'exportateur :
kubectl rollout restart deployment event-exporter -n monitoring
Surveillez les journaux pour détecter les erreurs :
kubectl logs -f deployment/event-exporter -n monitoring
Ces modifications ciblées aident à identifier le problème sans affecter l'ensemble du cluster.
Vérification et diagnostics
Après avoir apporté une modification de configuration ou un ajustement, vérifiez qu'elle résout le problème à l'aide de contrôles observables. Cette section fournit des commandes et des résultats attendus pour chaque couche.
1. Vérification du DNS
Depuis un pod de débogage, confirmez que le nom du service se résout vers la bonne ClusterIP :
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup webhook-receiver.default.svc.cluster.local
Attendu : une réponse avec la ClusterIP, sans erreur.
Testez aussi les domaines externes si des webhooks externes sont utilisés :
nslookup example.com
Si un DNS en amont personnalisé est mal configuré, corrigez la ConfigMap de CoreDNS et rechargez.
2. Disponibilité des points de terminaison
Vérifiez que le service possède des points de terminaison :
kubectl get endpoints webhook-receiver
Sortie attendue :
NAME ENDPOINTS AGE
webhook-receiver 10.244.1.5:8080 1d
Si les points de terminaison sont vides, vérifiez les étiquettes des pods et les sondes de disponibilité.
3. Tests de connectivité
Utilisez curl depuis un pod vers le point de terminaison du webhook (si HTTP) :
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- curl -v http://webhook-receiver.default.svc.cluster.local:8080/health
Attendu : une réponse HTTP 200 ou un résultat de contrôle de santé approprié.
Pour les services TCP, utilisez nc comme indiqué précédemment.
4. Test du flux d'événements
Créez un événement de test manuellement pour voir s'il est livré. Par exemple, créez un événement via l'API :
kubectl apply -f - <<EOF
apiVersion: v1
kind: Event
metadata:
name: test-event
namespace: default
message: "Test event for troubleshooting"
reason: Testing
involvedObject:
kind: Pod
name: dummy
namespace: default
source:
component: test
EOF
Observez ensuite les événements exportés ou reçus par le webhook. Consultez les journaux du récepteur webhook :
kubectl logs deployment/webhook-receiver -n default
Cherchez des entrées de requêtes entrantes.
5. Capture de paquets (si nécessaire)
Pour une analyse approfondie, capturez le trafic sur l'interface du pod. Identifiez d'abord le nœud et l'interface du pod :
kubectl get pod webhook-receiver-6b9c8d7f5-abc34 -o wide
Connectez-vous en SSH à ce nœud et utilisez tcpdump sur la veth du pod (nécessite les droits root). Utilisez nsenter ou crictl pour entrer dans l'espace de noms réseau du pod.
Une capture simple pour vérifier le trafic :
sudo tcpdump -i any -nn port 8080
Vous devriez voir des paquets SYN de l'IP du pod exportateur vers l'IP du pod webhook.
6. Vérifier les métriques et les journaux
Si le cluster dispose d'une surveillance (Prometheus, etc.), interrogez les métriques d'erreur de l'exportateur d'événements, par exemple kubernetes_event_exporter_errors_total.
Inspectez également les journaux d'audit du serveur API si la création d'événements échoue.
Utilisez le tableau suivant comme référence rapide de diagnostic :
| Symptôme | Cause probable | Commande de diagnostic | Résultat attendu |
|---|---|---|---|
| La résolution DNS échoue | CoreDNS mal configuré ou en panne | nslookup svc | Renvoie une IP |
| Connexion refusée | Aucun pod ne correspond au service | kubectl get endpoints | Points de terminaison non vides |
| Délai d'attente sur un appel externe | Sortie bloquée | nc -vz external: port | Connexion réussie |
| Événements non exportés | Config de l'exportateur incorrecte | kubectl logs exporter | Aucun message d'erreur |
| Échecs intermittents | Politique réseau qui supprime du trafic | kubectl describe netpol | Les règles autorisent le trafic |
Modes de défaillance et récupération
Même des modifications prudentes peuvent causer des problèmes. Préparez-vous à identifier les modes de défaillance et à récupérer rapidement.
1. Une modification DNS casse la résolution
Si la modification de la ConfigMap de CoreDNS provoque une panne DNS à l'échelle du cluster :
- Symptôme : toutes les commandes
nslookupdepuis les pods échouent, les services sont inaccessibles. - Récupération : restaurez la ConfigMap à sa version précédente. Si vous avez sauvegardé l'original, rétablissez-le :
kubectl apply -f coredns-configmap-backup.yaml
kubectl rollout restart deployment coredns -n kube-system
Vérifiez aussi le statut et les journaux des pods CoreDNS.
2. NetworkPolicy trop restrictive
Si une nouvelle NetworkPolicy bloque accidentellement tout trafic vers un espace de noms :
- Symptôme : les pods de l'espace de noms ne peuvent se connecter à rien, y compris au DNS.
- Récupération : supprimez la politique restrictive :
kubectl delete networkpolicy <policy-name> -n <namespace>
Ou appliquez une politique plus permissive.
3. Une règle de pare-feu bloque le trafic légitime
Si un changement de pare-feu sur un nœud bloque le trafic requis :
- Symptôme : la connectivité externe depuis le nœud échoue, affectant plusieurs pods.
- Récupération : annulez la règle de pare-feu. Pour iptables, restaurez depuis un ensemble de règles sauvegardé ou supprimez manuellement la règle.
Exemple pour supprimer une règle (si vous connaissez le numéro de ligne) :
sudo iptables -D OUTPUT -p tcp --dport 8080 -j REJECT
Assurez-vous d'utiliser la bonne chaîne et la bonne spécification de règle.
4. Erreur de configuration de l'exportateur d'événements
Si la configuration de l'exportateur est mal formée :
- Symptôme : le pod de l'exportateur plante ou les journaux affichent des erreurs.
- Récupération : restaurez la ConfigMap à la dernière version fonctionnelle et redémarrez le pod.
kubectl rollout undo deployment event-exporter -n monitoring
Cela fonctionne si la ConfigMap est suivie par la révision du déploiement.
5. Panne du serveur API ou de CoreDNS
Si un composant est en panne :
- Symptôme : impossible de créer des événements ou de résoudre le DNS.
- Récupération : redémarrez le composant (par exemple,
kubectl delete pod -n kube-system -l k8s-app=kube-dns). Assurez la haute disponibilité en ayant plusieurs réplicas.
6. Vérification après récupération
Relancez toujours les contrôles de diagnostic de la section Vérification pour confirmer le fonctionnement normal.
Pièges courants et comment les éviter
Au fil des années de dépannage du réseau des événements Kubernetes, certaines erreurs reviennent régulièrement. Les reconnaître tôt fait gagner du temps et évite des modifications inutiles.
1. Supposer que le réseau est le problème
De nombreux échecs de livraison d'événements sont en réalité des problèmes d'application ou de configuration, pas de réseau. Par exemple, le récepteur webhook peut renvoyer des erreurs 500 à cause d'un bug, ou l'exportateur peut abandonner des événements en raison d'un payload mal formé. Comment éviter : vérifiez toujours d'abord les journaux de l'expéditeur et du destinataire. Cherchez les erreurs au niveau applicatif avant de plonger dans le dépannage réseau.
2. Ignorer la mise en cache DNS
CoreDNS et la mise en cache côté client peuvent masquer les modifications DNS. Après avoir modifié des enregistrements DNS ou la configuration de CoreDNS, les pods peuvent continuer d'utiliser des entrées obsolètes. Comment éviter : utilisez kubectl rollout restart deployment pour redémarrer les pods qui ont besoin d'une résolution DNS fraîche, ou utilisez un TTL court pour les services de test. Dans un pod de débogage, exécutez nslookup avec -type=any pour voir tous les enregistrements.
3. NetworkPolicies trop larges
Une NetworkPolicy qui bloque involontairement le DNS (port 53) ou le trafic du kubelet peut provoquer des défaillances en cascade. Comment éviter : commencez par une politique de refus par défaut qui autorise explicitement les sorties nécessaires : DNS, serveur API et destinations de service spécifiques. Testez les politiques dans un espace de noms de staging avant de les appliquer à l'ensemble du cluster. Si une politique casse quelque chose, utilisez immédiatement kubectl delete networkpolicy pour rétablir la connectivité.
4. Règles de pare-feu ne correspondant pas à la sortie des nœuds
Les groupes de sécurité cloud ont souvent des règles de sortie distinctes pour différents sous-réseaux de nœuds. Ajouter une règle pour un sous-réseau alors que le pod exportateur tourne sur un autre entraîne des échecs intermittents. Comment éviter : vérifiez le sous-réseau du nœud du pod exportateur avec kubectl get pod -o wide, puis assurez-vous que la règle de sortie couvre ce sous-réseau. Utilisez les journaux de flux du fournisseur cloud pour confirmer.
5. Modifier plusieurs variables à la fois
Modifier simultanément le DNS, le pare-feu et la configuration de l'exportateur rend impossible l'identification de la cause première. Comment éviter : changez un paramètre à la fois, testez, et revenez en arrière s'il n'y a pas d'amélioration. Tenez un journal de chaque modification avec horodatage et résultats.
6. Négliger de vérifier les limites de ressources de l'exportateur d'événements
Les exportateurs d'événements peuvent être limités en CPU ou en mémoire, provoquant une livraison retardée des événements qui ressemble à un délai réseau. Comment éviter : vérifiez l'utilisation des ressources du pod avec kubectl top pod, et ajustez les limites si nécessaire. Surveillez les métriques de profondeur de file d'attente de l'exportateur.
Liste de contrôle opérationnelle
Utilisez cette liste de contrôle pour le dépannage de routine et la maintenance du réseau des événements Kubernetes. Pour chaque élément, attribuez un responsable unique (par exemple, Priya Shah, responsable de l'ingénierie) et une fréquence de revue (par exemple, hebdomadaire, mensuelle ou après chaque incident).
Avant le dépannage
- [ ] Confirmer la version du cluster et les détails de l'environnement. (Responsable : ingénieur DevOps, par exemple Alex Chen ; fréquence : début de chaque session de dépannage)
- [ ] Identifier tous les producteurs et consommateurs d'événements. (Responsable : architecte applicatif, par exemple Maria Garcia ; fréquence : revue mensuelle ou après modifications applicatives)
- [ ] S'assurer de l'accès aux outils et permissions nécessaires. (Responsable : administrateur du cluster, par exemple James Okafor ; fréquence : audit d'accès trimestriel)
- [ ] Documenter la configuration réseau actuelle (DNS, politiques, pare-feu). (Responsable : ingénieur réseau, par exemple Sarah Kim ; fréquence : après tout changement réseau ou mensuellement)
Pendant le dépannage
- [ ] Utiliser un pod de débogage pour les tests réseau ; ne pas modifier les pods de production. (Responsable : dépanneur de garde ; fréquence : chaque incident)
- [ ] Vérifier d'abord la résolution DNS :
nslookup service names. (Responsable : dépanneur de garde) - [ ] Vérifier les points de terminaison du service :
kubectl get endpoints. (Responsable : dépanneur de garde) - [ ] Tester la connectivité des ports :
nc -vz. (Responsable : dépanneur de garde) - [ ] Passer en revue les NetworkPolicies pour détecter les restrictions non intentionnelles. (Responsable : ingénieur réseau)
- [ ] Inspecter les journaux de l'exportateur pour les erreurs de livraison. (Responsable : ingénieur support applicatif)
- [ ] Utiliser la capture de paquets uniquement lorsque c'est nécessaire et avec prudence. (Responsable : ingénieur réseau senior)
Après le dépannage
- [ ] Documenter la cause première et la résolution. (Responsable : dépanneur de garde ; fréquence : immédiatement après la résolution)
- [ ] Mettre à jour les alertes de surveillance pour les conditions détectées (par exemple, nombre de points de terminaison, taux d'erreur de l'exportateur). (Responsable : chef d'équipe de surveillance, par exemple David Park ; fréquence : sous 2 jours ouvrés)
- [ ] Nettoyer les pods de débogage et les règles temporaires. (Responsable : dépanneur de garde ; fréquence : immédiatement après la résolution)
- [ ] Examiner les modifications pour la sécurité de la restauration. (Responsable : comité consultatif des changements ; fréquence : prochaine réunion de revue des changements)
Revue périodique
- [ ] Mettre régulièrement à jour CoreDNS et le CNI vers des versions prises en charge. (Responsable : administrateur du cluster ; fréquence : cycle de correctifs mensuel)
- [ ] Auditer les NetworkPolicies pour s'assurer qu'elles correspondent aux besoins des applications. (Responsable : ingénieur sécurité ; fréquence : trimestrielle)
- [ ] Tester le pipeline de livraison des événements après les mises à niveau du cluster ou les changements réseau. (Responsable : chef QA ; fréquence : après chaque mise à niveau ou changement majeur)
- [ ] Maintenir un runbook avec les problèmes connus et les correctifs. (Responsable : responsable de la documentation, par exemple Emily Nguyen ; fréquence : mise à jour après chaque incident)
Conclusion
Le dépannage du réseau des événements Kubernetes exige une approche méthodique : inventorier l'environnement, apporter des modifications ciblées et sûres, vérifier avec des commandes de diagnostic concrètes, et savoir comment récupérer en cas d'échec. En suivant les étapes de ce guide, vous pourrez rapidement déterminer si les problèmes proviennent du DNS, des ports, du routage ou des politiques de pare-feu, et les résoudre en toute confiance.
Prochaines étapes : appliquez la liste de contrôle opérationnelle dans votre cluster, validez la connectivité avec les commandes fournies, et envisagez de mettre en place une surveillance proactive de la livraison des événements. Grâce à ces pratiques, vous minimisez les temps d'arrêt et assurez la fiabilité des workflows pilotés par les événements.
En outre, adoptez une culture de modifications petites et réversibles et une propriété claire. Lorsque chaque membre de l'équipe connaît sa responsabilité et les commandes exactes à exécuter, les incidents se résolvent plus rapidement et se reproduisent moins souvent. Passez régulièrement en revue les pièges courants pour éviter qu'ils ne deviennent des pannes récurrentes. Enfin, considérez ce guide comme un document vivant : mettez-le à jour avec les leçons de chaque session de dépannage et partagez-le entre les équipes pour développer une expertise collective dans le réseau des événements Kubernetes.