Dépannage réseau des rôles Kubernetes : guide pratique

Introduction

Le dépannage réseau des rôles Kubernetes avec des exemples pratiques doit aider les opérateurs à passer d'un problème observé à un résultat vérifié. Commencez par identifier la version installée, la topologie de déploiement, les prérequis et le composant exact inspecté.

Cet article se concentre sur le réseau des rôles Kubernetes pour les développeurs, consultants DevOps et équipes techniques de startups. Il relie le DNS des rôles Kubernetes, les ports des rôles Kubernetes, la connectivité des rôles Kubernetes et le dépannage réseau des rôles Kubernetes aux commandes, sorties attendues, signaux de défaillance et décisions de récupération correspondant à la technologie sélectionnée.

L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier le résultat et documenter comment récupérer si l'état attendu n'est pas atteint.

Inventaire des versions et de l'environnement

Avant de toucher à toute configuration réseau, établissez une image claire de votre environnement Kubernetes. Cette section montre comment collecter les détails de version, lister les ressources actives et confirmer les prérequis afin que le dépannage parte d'un état connu plutôt que d'hypothèses.

Pourquoi la version et l'environnement comptent

Une erreur courante consiste à appliquer des commandes prévues pour Kubernetes 1.28 sur un cluster fonctionnant en 1.24. Par exemple, le format de sortie de kubectl auth can-i --list a changé autour de la v1.24. De même, certaines versions d'API RBAC (par exemple rbac.authorization.k8s.io/v1beta1) ont été supprimées dans les versions ultérieures. Connaître votre version exacte évite des erreurs trompeuses.

Étape 1 : Collecter les versions du cluster et du client

Exécutez ces commandes en lecture seule pour capturer l'environnement actuel :

kubectl version --short
kubectl cluster-info

La sortie attendue doit montrer à la fois les versions client et serveur, ainsi que le point de terminaison du plan de contrôle. Par exemple :

Client Version: v1.27.3
Server Version: v1.27.3
Kubernetes control plane is running at https://10.0.0.1:6443

Si le client et le serveur diffèrent de plus d'une version mineure, envisagez une mise à niveau ou l'utilisation d'un client compatible, car certaines options de commande peuvent être indisponibles.

Étape 2 : Vérifier les prérequis pour le réseau des rôles

Le contrôle d'accès basé sur les rôles (RBAC, Role-Based Access Control) est le fondement des autorisations liées au réseau. Vérifiez que les groupes d'API nécessaires sont disponibles :

kubectl api-versions | grep rbac.authorization.k8s.io

Sortie attendue pour un cluster moderne :

rbac.authorization.k8s.io/v1

Si rbac.authorization.k8s.io/v1 est manquant, le cluster peut être très ancien ou RBAC désactivé. Vérifiez les autorisations kubectl exec seulement après avoir confirmé l'existence de RBAC.

Étape 3 : Inventorier les rôles et liaisons existants

Listez tous les rôles et rôles de cluster pertinents pour le réseau. Par exemple, de nombreux plugins CNI ou maillages de services créent leurs propres rôles :

kubectl get roles --all-namespaces | grep -E 'network|net|cni|ingress|dns'
kubectl get clusterroles | grep -E 'network|net|cni|ingress|dns'

Recherchez des rôles nommés kube-dns, coredns, ingress-nginx ou similaires. Si un rôle est manquant, les pods d'application peuvent ne pas pouvoir lister les points de terminaison ou les services, entraînant des échecs DNS.

Étape 4 : Inspecter la configuration réseau des nœuds

Les paramètres au niveau des nœuds affectent le réseau des pods. Utilisez kubectl describe nodes pour voir les CIDR de pods alloués et les conditions :

kubectl describe node <votre-nom-de-nœud> | grep -A5 'PodCIDR'

Exemple de sortie :

PodCIDR: 10.244.0.0/24
PodCIDRs: 10.244.0.0/24

Si les PodCIDR sont vides, le nœud peut ne pas avoir été correctement initialisé par le plugin CNI. Cela entraîne souvent des pods bloqués en état ContainerCreating avec des erreurs réseau.

Étape 5 : Capturer les horodatages et la ligne de base

Pour toute session de dépannage, enregistrez l'heure actuelle et les commandes exécutées. Utilisez un script shell simple pour consigner les actions :

echo "$(date): Démarrage des diagnostics réseau" >> network-debug.log

Cette pratique aide à corréler les événements en cas d'incident et soutient l'analyse post-mortem.

Vérifications en lecture seule avant les modifications

Ne modifiez jamais une ressource avant de comprendre son état actuel. Utilisez ces commandes en lecture seule :

kubectl get pods -n kube-system -o wide
kubectl describe pod <pod-problème> -n <namespace>
kubectl logs <pod-problème> -n <namespace> --tail=50

Pour les boucles de crash, ajoutez --previous :

kubectl logs <pod-problème> -n <namespace> --previous

Ce n'est qu'après ces observations que vous devez planifier le plus petit changement possible, comme l'ajout d'une seule règle RBAC.

Chemin de configuration sûr

Apporter des modifications au réseau Kubernetes exige une approche disciplinée. Cette section fournit un chemin sûr du diagnostic à la correction vérifiée, minimisant le risque de conséquences imprévues.

Définir le plus petit changement justifié

Supposons qu'un pod dans le namespace web ne puisse pas résoudre les noms DNS. L'erreur dans les journaux est lookup service.default.svc.cluster.local: no such host. Au lieu d'accorder des autorisations larges, ciblez la capacité manquante spécifique.

D'abord, inspectez le rôle ou rôle de cluster qui devrait permettre la résolution DNS. Pour CoreDNS, les pods ont généralement besoin d'accéder au service coredns. Mais le problème peut être RBAC empêchant le pod de lister les points de terminaison dans son namespace. Vérifiez le compte de service du pod et ses rôles :

kubectl get pod <nom-du-pod> -n web -o jsonpath='{.spec.serviceAccountName}'

Puis listez les RoleBindings pour ce compte de service :

kubectl get rolebindings -n web -o json | jq '.items[] | select(.subjects[].name=="<nom-du-compte-de-service>")'

Si aucun rôle n'accorde get sur endpoints, le pod peut encore résoudre les noms de service via kube-dns car les requêtes DNS passent par le service DNS du cluster, mais certaines applications utilisent aussi l'API Kubernetes pour découvrir directement les points de terminaison. Dans ce cas, créez un rôle avec des autorisations minimales :

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: web
  name: endpoint-reader
rules:
- apiGroups: [""]
  resources: ["endpoints"]
  verbs: ["get", "list"]

Appliquez-le :

kubectl apply -f endpoint-reader-role.yaml

Puis liez-le au compte de service :

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: web
  name: read-endpoints
subjects:
- kind: ServiceAccount
  name: <nom-du-compte-de-service>
  namespace: web
roleRef:
  kind: Role
  name: endpoint-reader
  apiGroup: rbac.authorization.k8s.io

Appliquez et vérifiez.

Vérifier avec une requête réelle

Après avoir appliqué le changement RBAC, testez si le pod peut maintenant lister les points de terminaison :

kubectl auth can-i list endpoints --as=system:serviceaccount:web:<nom-du-compte-de-service> -n web

La sortie attendue doit être yes. Sinon, vérifiez la syntaxe du RoleBinding et le nom du compte de service.

Tester la connectivité réseau localement

Avant d'exposer un service via un équilibreur de charge ou une entrée, testez dans le cluster en utilisant le transfert de port :

kubectl port-forward svc/my-service 8080:80 -n web

Puis depuis un autre terminal, faites un curl sur le port local :

curl localhost:8080

Si cela réussit, le service et le réseau des pods fonctionnent ; le problème peut être le routage externe ou la configuration de l'ingress.

Garder un enregistrement des changements

Enregistrez toujours le changement exact pour un retour en arrière. Par exemple, sauvegardez le rôle d'origine :

kubectl get role endpoint-reader -n web -o yaml > endpoint-reader-backup.yaml

Si la nouvelle configuration cause des problèmes, restaurez avec :

kubectl apply -f endpoint-reader-backup.yaml

Ce chemin sûr évite les dommages permanents et accélère la récupération.

Vérification et diagnostics

Une fois un changement effectué ou un problème suspecté, une vérification systématique est essentielle. Cette section couvre comment diagnostiquer les problèmes réseau des rôles Kubernetes en utilisant des commandes ciblées et en interprétant leur sortie.

Diagnostiquer la résolution DNS

Le DNS est la défaillance réseau la plus courante dans Kubernetes. Commencez par vérifier les pods CoreDNS :

kubectl get pods -n kube-system -l k8s-app=kube-dns

Attendez-vous à ce que tous les pods soient en cours d'exécution et prêts. Sinon, décrivez-les :

kubectl describe pod -n kube-system -l k8s-app=kube-dns

Recherchez des événements comme FailedScheduling, CrashLoopBackOff, ou des erreurs concernant le volume configmap.

Testez la résolution DNS depuis un pod busybox :

kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup kubernetes.default

La sortie attendue doit inclure une adresse IP, telle que :

Server:    10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local

Name:      kubernetes.default
Address 1: 10.96.0.1

Si le nslookup expire ou renvoie server can't find, cela indique un problème de configuration DNS. Vérifiez le fichier /etc/resolv.conf du pod :

kubectl exec <nom-du-pod> -n <namespace> -- cat /etc/resolv.conf

Il doit contenir nameserver 10.96.0.10 (ou l'IP DNS de votre cluster) et les domaines de recherche. S'ils sont manquants, la dnsPolicy du pod peut être mal configurée ou le kubelet ne configure pas correctement le DNS.

Vérifier les ports et services

Les politiques réseau ou les services mal configurés bloquent souvent le trafic. Vérifiez les points de terminaison du service :

kubectl get endpoints <nom-du-service> -n <namespace>

Si les points de terminaison sont vides, le sélecteur de service ne correspond à aucun pod. Comparez le sélecteur de service avec les étiquettes des pods :

kubectl get service <nom-du-service> -n <namespace> -o jsonpath='{.spec.selector}'; echo
kubectl get pods -n <namespace> --show-labels

Exemple de discordance : le sélecteur de service est app: myapp mais les pods ont app: my-app. Corrigez le sélecteur ou l'étiquette.

Vérifiez que le port cible écoute réellement dans le pod :

kubectl exec <nom-du-pod> -n <namespace> -- netstat -tulpn

Ou si netstat n'est pas disponible, utilisez ss ou inspectez le processus du conteneur.

Tester la connectivité entre les pods

Utilisez kubectl exec pour exécuter curl d'un pod à un autre :

kubectl exec <pod-source> -n <namespace> -- curl http://<service-de-destination>.<namespace>.svc.cluster.local:80

Si curl échoue, vérifiez les politiques réseau dans le namespace :

kubectl get networkpolicies -n <namespace>

Une NetworkPolicy peut refuser tout le trafic entrant sauf autorisation explicite. Exemple de politique qui autorise uniquement depuis le même namespace :

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-all
  namespace: web
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  - Egress

Cela bloquerait tout le trafic inter-pods à moins que d'autres politiques ne l'autorisent. Pour dépanner temporairement, vous pouvez supprimer la politique (mais notez le risque) :

kubectl delete networkpolicy default-deny-all -n web

Mieux : examinez la politique et ajoutez les règles d'entrée nécessaires.

Valider les autorisations RBAC

Parfois, les outils réseau dans un pod échouent parce que le compte de service manque d'autorisations pour interroger l'API. Utilisez kubectl auth can-i pour vérifier :

kubectl auth can-i list pods --as=system:serviceaccount:web:default -n web

Si la sortie est no, le pod ne peut pas lister les pods, ce qui peut être nécessaire pour la découverte de services. Ajoutez le rôle et le RoleBinding requis comme décrit dans le chemin de configuration sûr.

Lire les événements et journaux des composants réseau

Pour les plugins CNI comme Calico, Flannel ou Cilium, inspectez leurs pods et journaux :

kubectl get pods -n kube-system | grep -E 'calico|flannel|cilium'
kubectl logs <pod-cni> -n kube-system --tail=50

Recherchez des erreurs comme failed to allocate IP, netlink: operation not permitted, ou des problèmes avec etcd. Celles-ci indiquent des problèmes réseau plus profonds qui peuvent nécessiter un débogage au niveau du nœud.

Utiliser kubectl describe pour les détails du service

kubectl describe service montre les événements et les points de terminaison :

kubectl describe service my-service -n web

La sortie inclut :

Endpoints: 10.244.1.5:8080,10.244.2.3:8080

Si les points de terminaison sont présents, le trafic devrait atteindre les pods. Sinon, revoyez les sondes de préparation des pods.

Modes de défaillance et récupération

Les défaillances réseau dans Kubernetes peuvent avoir diverses causes racines. Cette section décrit les modes de défaillance courants, comment les reconnaître et les étapes pour récupérer.

Mode de défaillance 1 : Le pod ne peut atteindre aucune adresse externe

Symptômes : Les pods peuvent résoudre le DNS interne mais ne peuvent pas atteindre les sites web externes ; le trafic sortant échoue.

Diagnostic : Vérifiez si le pod a une NetworkPolicy de sortie bloquant tout le trafic sortant. Listez les politiques :

kubectl get networkpolicies -n <namespace>

Vérifiez la table de routage du pod :

kubectl exec <nom-du-pod> -n <namespace> -- ip route

Doit montrer une route par défaut via l'IP du nœud ou la superposition. Si elle est manquante, le CNI peut être mal configuré.

Récupération : Ajoutez une politique de sortie autorisant le DNS et HTTP/HTTPS :

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-egress-external
  namespace: <namespace>
spec:
  podSelector: {}
  policyTypes:
  - Egress
  egress:
  - to:
    - namespaceSelector: {}
    ports:
    - protocol: UDP
      port: 53
  - to:
    - ipBlock:
        cidr: 0.0.0.0/0
        except:
        - 10.0.0.0/8
        - 172.16.0.0/12
        - 192.168.0.0/16
    ports:
    - protocol: TCP
      port: 443

Appliquez et testez la connectivité externe.

Mode de défaillance 2 : Résolution DNS intermittente

Symptômes : Parfois, les requêtes DNS échouent, provoquant des erreurs d'application comme UnknownHostException.

Diagnostic : Vérifiez les limites de ressources et le nombre de réplicas de CoreDNS :

kubectl get deployment coredns -n kube-system -o yaml | grep -A5 resources
kubectl get pods -n kube-system -l k8s-app=kube-dns -o wide

Si les pods CoreDNS sont tués par manque de mémoire (OOMKilled), augmentez la limite de mémoire. S'il n'y a qu'un seul réplica et qu'une panne de nœud survient, le DNS devient indisponible. Définissez au moins deux réplicas :

kubectl scale deployment coredns -n kube-system --replicas=2

Vérifiez aussi la configuration du plugin autopath dans le Corefile si vous utilisez des domaines personnalisés.

Mode de défaillance 3 : Points de terminaison de service manquants

Symptômes : Le service ne route pas le trafic ; kubectl get endpoints ne montre aucune adresse.

Diagnostic : Confirmez la correspondance du sélecteur et la préparation des pods :

kubectl get pods -n <namespace> -l app=myapp -o wide
kubectl describe pod <nom-du-pod> -n <namespace> | grep -A10 Conditions

Si les pods ne sont pas prêts, vérifiez la configuration de la sonde de préparation et les journaux.

Récupération : Corrigez la sonde de préparation. Exemple :

readinessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5

Après que le pod devient prêt, les points de terminaison devraient apparaître automatiquement.

Mode de défaillance 4 : RBAC refuse l'accès aux ressources réseau

Symptômes : Les journaux du pod montrent des erreurs forbidden en essayant de lister les services ou points de terminaison via l'API Kubernetes.

Diagnostic : Utilisez kubectl auth can-i en tant que compte de service du pod :

kubectl auth can-i list services --as=system:serviceaccount:web:myapp -n web

Récupération : Créez un rôle avec list et get sur services et endpoints, et liez-le au compte de service.

Mode de défaillance 5 : Plugin CNI ne fonctionne pas

Symptômes : Les nouveaux pods restent en ContainerCreating avec des événements comme failed to setup network ou network plugin not ready.

Diagnostic : Vérifiez les pods CNI :

kubectl get pods -n kube-system | grep -i calico
kubectl logs <pod-calico> -n kube-system --tail=50

Recherchez des erreurs de connexion à etcd ou des problèmes IPAM.

Récupération : Redémarrez le pod CNI ou le nœud. Si persistant, vérifiez le fichier de configuration CNI dans /etc/cni/net.d/ sur le nœud. Assurez-vous que le binaire du plugin existe dans /opt/cni/bin/.

Récupération générale : Retour en arrière et restauration

Ayez toujours un plan de retour en arrière. Par exemple, si un changement dans une ConfigMap casse le DNS, restaurez la ConfigMap précédente :

kubectl rollout undo deployment coredns -n kube-system

Ou appliquez une sauvegarde YAML enregistrée.

Liste de contrôle des opérations

Utilisez cette liste de contrôle avant, pendant et après le dépannage réseau des rôles Kubernetes. Elle garantit cohérence et sécurité.

Liste de contrôle pré-incident

• [ ] Version du cluster vérifiée avec kubectl version --short (la sortie attendue montre les versions client et serveur, par exemple v1.27.3)
• [ ] Groupe d'API RBAC rbac.authorization.k8s.io/v1 disponible (kubectl api-versions | grep rbac.authorization.k8s.io renvoie rbac.authorization.k8s.io/v1)
• [ ] Rôles et rôles de cluster actuels inventoriés (kubectl get roles --all-namespaces, kubectl get clusterroles)
• [ ] Configuration réseau des nœuds capturée (kubectl describe node <nœud> | grep -A5 PodCIDR montre PodCIDR comme 10.244.0.0/24)
• [ ] Outils de diagnostic disponibles : image busybox pour les tests DNS, client kubectl avec autorisations appropriées

Liste de contrôle pendant l'incident

• [ ] Collecter l'état du système : kubectl get pods -n <namespace> -o wide, kubectl get events --sort-by=.metadata.creationTimestamp
• [ ] Inspecter les journaux du pod affecté : kubectl logs <pod> -n <namespace> --tail=100, et en cas de boucle de crash, ajouter --previous
• [ ] Vérifier la résolution DNS depuis un pod de débogage : kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup kubernetes.default (IP attendue comme 10.96.0.1)
• [ ] Vérifier les points de terminaison du service : kubectl get endpoints <service> -n <namespace> (doit lister les IP des pods)
• [ ] Tester la connectivité pod à pod avec curl depuis le pod source vers le nom DNS du service de destination
• [ ] Inspecter les NetworkPolicies : kubectl get networkpolicies -n <namespace>
• [ ] Vérifier les autorisations RBAC : kubectl auth can-i list endpoints --as=system:serviceaccount:<ns>:<sa> -n <ns> (attendu yes)
• [ ] Examiner les pods et journaux du plugin CNI : kubectl logs <pod-cni> -n kube-system --tail=50

Liste de contrôle de vérification post-incident

• [ ] Tous les pods affectés sont en cours d'exécution et prêts (kubectl get pods -n <namespace> montre 1/1 Running)
• [ ] Résolution DNS stable sur plusieurs requêtes (nslookup réussit sur 10 tentatives consécutives)
• [ ] Points de terminaison du service peuplés avec les IP correctes des pods
• [ ] Le trafic sortant externe fonctionne si nécessaire (test avec curl http://example.com depuis le pod)
• [ ] Changements RBAC documentés et enregistrés dans le contrôle de version
• [ ] Règles NetworkPolicy vérifiées pour autoriser le trafic nécessaire et refuser les autres
• [ ] Plan de retour en arrière testé : restaurer le YAML précédent et confirmer le retour à l'état de base

Exemple : Remplir la liste de contrôle pour un problème DNS

Supposons qu'un pod dans le namespace web échoue au DNS. Voici comment appliquer la liste de contrôle :

1. Pré-incident : Confirmer le cluster v1.27.3, RBAC v1 disponible, aucun rôle manquant évident.
2. Pendant l'incident :

• Exécuter kubectl get pods -n web -o wide et voir le pod web-frontend-7b9f8c6d5-abcde sur le nœud worker-1.
• Vérifier les journaux : kubectl logs web-frontend-7b9f8c6d5-abcde -n web --tail=50 montre lookup api.github.com: no such host.
• Exécuter le pod de débogage nslookup : kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup api.github.com renvoie server can't find api.github.com: NXDOMAIN.
• Vérifier les journaux CoreDNS : kubectl logs -n kube-system -l k8s-app=kube-dns --tail=100 montre des erreurs SERVFAIL et timeout.
• Vérifier la ConfigMap CoreDNS : kubectl get configmap coredns -n kube-system -o yaml montre un DNS amont mal configuré.

1. Récupération : Corriger la ConfigMap amont vers 8.8.8.8, redémarrer CoreDNS.
2. Post-incident : Réexécuter nslookup, vérifier le succès, documenter le changement.

Ce flux de travail concret garde le dépannage organisé et réduit le temps moyen de résolution.

Conclusion

Le dépannage réseau des rôles Kubernetes avec des exemples pratiques n'est utile que si chaque recommandation est limitée à la version, observable et réversible là où la technologie le permet. Copier une commande sans vérifier les prérequis et la sortie attendue n'est pas une procédure d'exploitation.

Comme prochaine étape, choisissez une vérification à faible risque pour le réseau des rôles Kubernetes, enregistrez l'état actuel, exécutez la vérification documentée, comparez le résultat avec le signal attendu et passez en revue les dépendances telles que le Role Binding, le Cluster Role et le Service Account.

Un flux de travail technique fiable rend la défaillance visible, protège les valeurs sensibles, limite les changements à la ressource visée et définit la vérification de récupération avant qu'un incident ne force la décision.

Recommandations finales

• Toujours commencer par des observations en lecture seule. Utilisez kubectl get, describe et logs avant de faire des changements.
• Faire un changement à la fois. Évitez les modifications en masse des rôles ou NetworkPolicies ; elles peuvent avoir des interactions inattendues.
• Automatiser les vérifications lorsque c'est possible. Utilisez des scripts pour exécuter la liste de contrôle des opérations et alerter sur les anomalies.
• Garder la documentation vivante. Après chaque incident, mettez à jour les runbooks avec les nouvelles découvertes et étapes de récupération.
• Pratiquer la récupération. Testez régulièrement les procédures de retour en arrière dans un environnement de préproduction.

En suivant ce guide, vous pouvez dépanner en toute confiance les problèmes réseau des rôles Kubernetes, minimiser les temps d'arrêt et maintenir un cluster résilient.