Dépannage réseau des classes d'Ingress Kubernetes : guide pratique avec exemples

Introduction

Les problèmes de réseau liés aux classes d'Ingress Kubernetes sont parmi les plus difficiles à diagnostiquer, car ils impliquent plusieurs composants : le contrôleur Ingress, la ressource Ingress, les Services, les Endpoints, le DNS et les NetworkPolicies. Une requête qui échoue au niveau du navigateur peut avoir traversé plusieurs couches, chacune avec ses propres journaux et particularités de configuration. Ce guide propose une approche structurée du dépannage, en partant de l'observation des symptômes jusqu'à la confirmation de la correction, avec des commandes concrètes et les sorties attendues à chaque étape.

Nous nous concentrons sur le concept de classe Ingress, qui permet à plusieurs contrôleurs Ingress de coexister dans un cluster et détermine quel contrôleur traite une ressource Ingress donnée. Une classe Ingress mal configurée est une cause fréquente d'erreurs 404, de délais d'attente et de services inaccessibles. Vous apprendrez à inspecter votre environnement, à suivre un chemin de configuration sûr, à exécuter des diagnostics ciblés, à identifier les modes de défaillance et à appliquer les procédures de récupération.

Ce guide s'adresse aux développeurs, ingénieurs DevOps et équipes techniques de startups qui exploitent des clusters Kubernetes et doivent résoudre les problèmes de réseau Ingress sans aggraver la situation. Nous insistons sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, protéger les secrets et toujours vérifier la récupération.

Inventaire des versions et de l'environnement

Avant de toucher à quoi que ce soit, rassemblez les versions exactes et la topologie. Les composants Kubernetes évoluent rapidement, et ce qui fonctionne en 1.25 peut se comporter différemment en 1.30. Exécutez ces commandes en lecture seule pour établir une base de référence.

Tout d'abord, confirmez la version du cluster et le contexte :

kubectl version --short
kubectl config current-context

La sortie attendue inclut les versions du client et du serveur, par exemple Client Version: v1.29.1 et Server Version: v1.29.2. Notez le contexte pour vous assurer de travailler sur le bon cluster, surtout si vous gérez plusieurs environnements.

Ensuite, identifiez le contrôleur Ingress et sa version. Les contrôleurs courants incluent NGINX Ingress Controller, Traefik, HAProxy et des contrôleurs spécifiques au cloud comme AWS Load Balancer Controller. Vérifiez l'espace de noms et les pods :

kubectl get pods -n ingress-nginx -o wide

Cela affiche les noms des pods, leur statut, leurs adresses IP et leur placement sur les nœuds. Pour chaque pod, vérifiez l'étiquette d'image :

kubectl get pods -n ingress-nginx -o jsonpath='{.items[*].spec.containers[*].image}'

Par exemple, la sortie pourrait être registry.k8s.io/ingress-nginx/controller:v1.9.4. Notez cette version et comparez-la avec la matrice de compatibilité officielle.

Les prérequis pour que la classe Ingress fonctionne incluent :

• Un contrôleur Ingress déployé et en cours d'exécution (par exemple, ingress-nginx).
• La ressource IngressClass définie (soit une classe par défaut, soit une classe personnalisée).
• La ressource Ingress référençant la bonne IngressClass via spec.ingressClassName.
• Des Services de type ClusterIP ou NodePort derrière l'Ingress.
• Des autorisations RBAC correctes pour le contrôleur.

Pour voir les IngressClasses existantes :

kubectl get ingressclass

Exemple de sortie :

NAME    CONTROLLER                      PARAMETERS   AGE
nginx   k8s.io/ingress-nginx            <none>       30d

Notez le champ CONTROLLER ; il doit correspondre à l'argument --controller-class du contrôleur. Vérifiez les journaux du contrôleur pour confirmer :

kubectl logs -n ingress-nginx deployment/ingress-nginx-controller | grep -i class

Vous devriez voir des lignes comme Using ingress class: nginx ou Watching for ingress class: nginx.

Capturez toujours l'état actuel et les horodatages avant de faire des modifications. Utilisez kubectl get ingress -A -o yaml > ingress-backup-$(date +%Y%m%d-%H%M%S).yaml pour sauvegarder les ressources Ingress. Pour les secrets, ne les imprimez jamais ; vérifiez plutôt leur existence et leur propriétaire avec kubectl get secret <tls-secret> -n <namespace> -o yaml et vérifiez uniquement le metadata.name.

Chemin de configuration sûr

Dans un cluster de production, chaque modification doit être limitée et réversible. Suivez ce chemin lors de la modification des ressources liées à l'Ingress.

Tout d'abord, assurez-vous de comprendre la configuration actuelle. Exportez la ressource Ingress concernée :

kubectl get ingress my-ingress -n my-app -o yaml

Recherchez ces champs critiques :

spec:
  ingressClassName: nginx
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-service
            port:
              number: 80

Vérifiez que ingressClassName correspond à une IngressClass existante. S'il est manquant, la IngressClass par défaut du cluster (s'il y en a une) peut être utilisée, ce qui peut prêter à confusion.

Faites une petite modification à la fois. Par exemple, si vous devez ajouter une nouvelle règle d'hôte, appliquez un patch plutôt que de remplacer toute la ressource :

kubectl patch ingress my-ingress -n my-app --type='json' -p='[{"op": "add", "path": "/spec/rules/-", "value": {"host": "api.example.com", "http": {"paths": [{"path": "/api", "pathType": "Prefix", "backend": {"service": {"name": "api-service", "port": {"number": 8080}}}}]}}}]'

Après l'application, vérifiez le statut de l'Ingress :

kubectl get ingress my-ingress -n my-app -o wide

La sortie attendue inclut une adresse (comme 192.168.1.100 ou example-lb.elb.amazonaws.com) et aucun événement d'erreur. Si l'adresse est en attente, vérifiez les journaux du contrôleur.

Testez localement avant d'exposer publiquement. Utilisez kubectl port-forward pour accéder directement au service, en contournant le contrôleur Ingress :

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

Ensuite, exécutez curl http://localhost:8080 depuis votre machine. Cela permet d'isoler si le service backend est fonctionnel.

Pour un test réaliste via le contrôleur Ingress, utilisez kubectl port-forward vers le pod du contrôleur :

kubectl port-forward -n ingress-nginx svc/ingress-nginx-controller 8081:80

Envoyez ensuite une requête avec l'en-tête Host :

curl -H "Host: app.example.com" http://localhost:8081/

Si cela fonctionne mais que l'accès externe échoue, le problème est probablement lié au DNS, à l'équilibreur de charge ou au pare-feu.

Documentez toujours le chemin de récupération : enregistrez le manifeste précédent avant de le modifier. Par exemple :

kubectl get ingress my-ingress -n my-app -o yaml > my-ingress-original.yaml

Si la modification casse quelque chose, restaurez avec kubectl apply -f my-ingress-original.yaml.

Vérification et diagnostics

Après toute modification ou lors d'un dépannage, exécutez un ensemble systématique de vérifications de l'extérieur vers l'intérieur.

1. Résolution DNS

Confirmez que le nom d'hôte se résout en l'adresse IP externe du contrôleur Ingress ou de l'équilibreur de charge.

dig app.example.com +short

Sortie attendue : l'adresse IP externe de l'équilibreur de charge ou l'IP NodePort du contrôleur Ingress. Comparez avec kubectl get svc -n ingress-nginx ingress-nginx-controller pour voir EXTERNAL-IP.

Si le DNS est incorrect, inspectez les enregistrements du fournisseur DNS. Pour un DNS géré par Kubernetes (comme ExternalDNS), vérifiez ses journaux :

kubectl logs -n external-dns deployment/external-dns

Cherchez des messages d'erreur concernant la création d'enregistrements ou des annotations manquantes.

2. Journaux du contrôleur Ingress

Les journaux du contrôleur Ingress sont le premier endroit à consulter pour les erreurs de routage.

kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=50

Surveillez les entrées comme ingress/default/my-ingress: no active endpoints ou service "default/web-service" does not have any active Endpoint. Celles-ci indiquent des problèmes de service backend.

Activez temporairement la journalisation de débogage si nécessaire (mais soyez prudent avec les données sensibles). Pour NGINX Ingress, définissez --v=3 pour plus de verbosité.

3. État de la ressource Ingress

Vérifiez les événements et le statut :

kubectl describe ingress my-ingress -n my-app

Cherchez la section Events avec des avertissements tels que Failed to reload ou no matches for kind.

4. Service backend et Endpoints

Assurez-vous que le service a des endpoints :

kubectl get endpoints web-service -n my-app

La sortie attendue montre les adresses IP des pods :

NAME          ENDPOINTS           AGE
web-service   10.244.1.5:8080     1h

Si elle est vide, le sélecteur du service ne correspond à aucun pod. Vérifiez les étiquettes des pods :

kubectl get pods -n my-app --show-labels

Vérifiez le sélecteur du service :

kubectl get svc web-service -n my-app -o jsonpath='{.spec.selector}'

Exemple : {"app":"web"}. Assurez-vous que les pods ont cette étiquette.

5. Connectivité à travers l'Ingress

Utilisez curl avec une sortie verbeuse pour voir où cela échoue :

curl -v http://app.example.com/

Notez les codes de statut : 404 signifie que la règle de routage n'est pas trouvée, 502 signifie que le backend est inaccessible, 503 signifie qu'aucun endpoint n'est disponible, 504 signifie un délai d'attente.

Pour les problèmes HTTPS, testez avec openssl s_client :

echo | openssl s_client -connect app.example.com:443 -servername app.example.com

Vérifiez la chaîne de certificats et l'expiration.

6. NetworkPolicies

Les NetworkPolicies peuvent bloquer le trafic entre les pods du contrôleur Ingress et les pods backend. Listez les politiques dans l'espace de noms du backend :

kubectl get networkpolicy -n my-app

Si elles existent, inspectez-les pour vérifier les entrées autorisées depuis l'espace de noms du contrôleur Ingress :

kubectl get networkpolicy -n my-app allow-from-ingress -o yaml

Assurez-vous que la politique autorise le trafic depuis l'espace de noms du contrôleur Ingress (par exemple, ingress-nginx) sur le port du backend.

Modes de défaillance et récupération

Modes de défaillance courants et comment les récupérer.

Défaillance 1 : Incompatibilité de l'IngressClass

Symptôme : La ressource Ingress est créée mais aucune adresse n'est attribuée, ou les requêtes renvoient une erreur 404 du contrôleur. Les journaux du contrôleur affichent Ignoring ingress because of ingress class.

Diagnostic :

kubectl get ingress my-ingress -o jsonpath='{.spec.ingressClassName}' && echo
kubectl get ingressclass

Si le nom de classe est vide ou ne correspond pas, le contrôleur ne traitera pas l'Ingress.

Récupération : Définissez le bon ingressClassName :

kubectl patch ingress my-ingress -n my-app -p '{"spec":{"ingressClassName":"nginx"}}'

Ou si cet Ingress doit être géré par un contrôleur non par défaut, assurez-vous que ce contrôleur est déployé.

Défaillance 2 : Le service backend n'a pas d'endpoints

Symptôme : Erreur 503 Service Unavailable de l'Ingress, les journaux du contrôleur affichent no active endpoints.

Diagnostic :

kubectl get endpoints web-service -n my-app

Si les endpoints sont vides, vérifiez la disponibilité des pods :

kubectl get pods -n my-app -o wide

Cherchez les pods non prêts et décrivez-les :

kubectl describe pod <pod-name> -n my-app

Vérifiez les échecs de sonde de disponibilité. Les causes courantes incluent un mauvais port de conteneur, une configuration manquante ou des boucles de crash.

Récupération : Corrigez le problème sous-jacent du pod. S'il s'agit d'un incident temporaire, la mise à l'échelle du déploiement peut aider :

kubectl scale deployment web-deployment -n my-app --replicas=3

Vérifiez ensuite que les endpoints sont remplis.

Défaillance 3 : Certificat TLS manquant ou expiré

Symptôme : Les requêtes HTTPS échouent avec des avertissements de certificat ou des erreurs de handshake.

Diagnostic :

kubectl get secret my-tls-secret -n my-app

S'il est manquant, l'Ingress servira quand même avec un certificat factice. Vérifiez les détails du certificat :

kubectl get secret my-tls-secret -n my-app -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -dates

Récupération : Créez ou renouvelez le secret. Pour une configuration Let's Encrypt, assurez-vous que cert-manager fonctionne. Si vous n'utilisez pas cert-manager, générez un nouveau certificat et mettez à jour le secret :

kubectl create secret tls my-tls-secret --cert=path/to/tls.crt --key=path/to/tls.key -n my-app

Déclenchez ensuite un rechargement de l'Ingress (généralement automatique).

Défaillance 4 : CrashLoopBackOff du pod du contrôleur Ingress

Symptôme : Les pods du contrôleur Ingress redémarrent, toutes les ressources Ingress cessent de fonctionner.

Diagnostic :

kubectl get pods -n ingress-nginx

Si le statut est CrashLoopBackOff, vérifiez les journaux du conteneur précédent :

kubectl logs -n ingress-nginx <pod-name> --previous

Cherchez des paniques, des erreurs de configuration ou des problèmes de permissions.

Récupération : Les correctifs courants incluent l'augmentation des limites de mémoire, la correction des RBAC ou la correction de la ConfigMap du contrôleur. Par exemple, si l'erreur mentionne un modèle personnalisé, revenez à une version connue de la ConfigMap :

kubectl get configmap ingress-nginx-controller -n ingress-nginx -o yaml > cm-backup.yaml
kubectl apply -f known-good-cm.yaml

Redémarrez ensuite le contrôleur :

kubectl rollout restart deployment ingress-nginx-controller -n ingress-nginx

Défaillance 5 : NetworkPolicy bloquant le trafic

Symptôme : Le contrôleur Ingress peut atteindre le service (aucune erreur) mais les requêtes expirent ou sont réinitialisées. Ou les pods backend ne reçoivent pas le trafic de l'Ingress.

Diagnostic : Vérifiez si des NetworkPolicies existent dans l'espace de noms du backend et si elles autorisent l'entrée depuis l'espace de noms du contrôleur.

kubectl get networkpolicy -n my-app

Si des politiques existent, inspectez-les pour les règles d'entrée. Par exemple, une politique pourrait n'autoriser que depuis app=frontend mais pas depuis ingress-nginx.

Récupération : Ajoutez une règle d'entrée pour autoriser le trafic depuis l'espace de noms du contrôleur Ingress. Pour NGINX Ingress, les pods du contrôleur ont généralement des étiquettes comme app.kubernetes.io/name=ingress-nginx dans l'espace de noms ingress-nginx. Créez une NetworkPolicy qui autorise l'entrée depuis cet espace de noms sur le port du backend, ou ajoutez une règle à la politique existante.

Liste de contrôle opérationnelle

Utilisez cette liste comme guide pour les problèmes de réseau Ingress. Remplacez les valeurs d'exemple par les vôtres.

• [ ] Confirmer le contexte du cluster et les versions : kubectl config current-context et kubectl version --short.
• [ ] Identifier le contrôleur Ingress et sa version : kubectl get pods -n ingress-nginx -o wide et vérifier les étiquettes d'image.
• [ ] Lister les IngressClasses et s'assurer qu'une correspond au spec.ingressClassName de l'Ingress : kubectl get ingressclass et kubectl get ingress <name> -o yaml.
• [ ] Vérifier l'attribution d'adresse de l'Ingress : kubectl get ingress -A - l'adresse doit être renseignée, pas <pending>.
• [ ] Tester la résolution DNS : dig app.example.com +short correspond à l'IP externe du contrôleur Ingress.
• [ ] Vérifier les endpoints du service backend : kubectl get endpoints <service> -n <namespace> - endpoints listés.
• [ ] Vérifier la disponibilité des pods backend : kubectl get pods -n <namespace> - tous prêts.
• [ ] Examiner les journaux du contrôleur Ingress : kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=100 - pas d'erreurs no active endpoints ou d'incompatibilité de classe.
• [ ] Si TLS est utilisé, vérifier que le secret existe et que le certificat est valide : kubectl get secret <tls-secret> -n <namespace> et vérifier l'expiration.
• [ ] Vérifier les NetworkPolicies dans l'espace de noms du backend : kubectl get networkpolicy -n <namespace> - si présentes, s'assurer qu'elles autorisent l'entrée depuis l'espace de noms du contrôleur.
• [ ] Tester localement : kubectl port-forward -n <namespace> svc/<service> <local-port>:<service-port> et curl.
• [ ] Tester via l'Ingress : curl -v http://<host>/ et observer le code de statut (200, 404, 502, 503, 504).

Pour chaque modification, enregistrez l'état précédent et la commande utilisée, afin que la récupération soit possible. Tenez un journal des horodatages et des sorties pour l'examen post-incident.

Conclusion

Le dépannage des problèmes de réseau liés aux classes d'Ingress Kubernetes nécessite une observation méthodique et une vérification par couches. Commencez par l'inventaire de l'environnement pour connaître vos versions et votre topologie. Modifiez ensuite les configurations en toute sécurité avec des sauvegardes et des tests locaux. Exécutez les diagnostics du DNS jusqu'au niveau des pods, et connaissez les modes de défaillance courants comme l'incompatibilité de l'IngressClass, les endpoints manquants, les problèmes de certificat, les plantages du contrôleur et les NetworkPolicies.

Un flux de travail fiable rend la défaillance visible, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision. Appliquez la liste de contrôle opérationnelle comme point de départ, adaptez-la à votre cluster et vérifiez toujours que le correctif fonctionne non seulement isolément mais pour le trafic utilisateur réel.

Comme prochaine étape, choisissez une vérification à faible risque de la liste, comme la vérification de l'alignement de l'IngressClass, et exécutez-la dans votre environnement. Enregistrez l'état actuel, exécutez la vérification, comparez la sortie avec le signal attendu et examinez les dépendances comme les Services et les NetworkPolicies. Cette discipline transforme le dépannage chaotique en un processus calme et reproductible.