Kubernetes Ingress : erreurs courantes et correctifs avec exemples pratiques - guide d'implémentation

Introduction

Les Kubernetes Ingress common errors surviennent souvent quand l'équipe passe d'un déploiement qui « fonctionne sur la machine » à une exécution cohérente dans des environnements variés. Ce guide met l'accent sur l'action : quoi configurer, quelle commande prouve que la configuration marche, et à quoi ressemble l'échec quand quelque chose manque ou est mal branché. Il relie explicitement Kubernetes Ingress fixes, Kubernetes Ingress error messages, Kubernetes Ingress debugging et Kubernetes Ingress troubleshooting pour permettre un passage fluide du concept à la vérification locale et à la reproductibilité en CI/CD (par exemple GitLab CI/CD).

Objectif pratique : comprendre les composants en mouvement (Ingress, IngressClass, Service, Endpoints, Pods, TLS), les tester localement, et éviter les surprises quand le schéma est réutilisé dans un environnement proche de la production.

Workflow Overview

La boucle de travail efficace pour les erreurs d'Ingress tient en trois étapes :

• Configurer un élément unique (Ingress, Service, Secret TLS...).
• Observer l'état réel avec des commandes ciblées.
• Documenter ce qui casse quand la pièce est absente, mal configurée ou testée dans un contexte différent (laptop, runner, hôte de prod).

Hypothèses fréquentes à expliciter : chemins locaux, tags d'images Docker, noms de réseau, fichiers d'environnement, limites de ressources, permissions et différences de namespaces. Ces hypothèses varient entre postes, runners et hôtes, et impactent directement le comportement du contrôleur Nginx et des objets Kubernetes.

Contrôles Kubernetes rapides pour le diagnostic :

• kubectl get pods -o wide pour une vue d'ensemble et la localisation des workloads.
• kubectl describe pod <name> pour les détails de planification et d'événements.
• kubectl logs <name> --previous en cas de crash loops.
• kubectl rollout status deployment/<name> pour confirmer un déploiement avant de tester l'entrée réseau.
• kubectl get ingress -A et kubectl describe ingress <name> pour voir les règles, l'IngressClass, les événements et l'adresse assignée.
• kubectl logs deploy/ingress-nginx-controller -n ingress-nginx pour les messages du contrôleur Nginx (si vous utilisez ingress-nginx).

Gardez le test local petit : appliquez un seul manifest, inspectez les ressources générées, et vérifiez le trafic avec kubectl port-forward ou un Service de type local avant de passer à un load balancer cloud.

Local Pilot Plan

Commencez par un schéma minimal : un Deployment exposé par un Service, et un Ingress qui route vers ce Service. Cet exemple illustre les champs essentiels (IngressClass, règles HTTP, TLS) et servira de base aux scénarios d'erreurs.

Exemple de Service et Ingress (simplifié) :

apiVersion: v1
kind: Service
metadata:
  name: web-svc
spec:
  selector:
    app: web
  ports:
    - name: http
      port: 80
      targetPort: 8080
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web-ing
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/"
spec:
  ingressClassName: nginx
  rules:
    - host: web.local
      http:
        paths:
          - path: "/"
            pathType: Prefix
            backend:
              service:
                name: web-svc
                port:
                  number: 80
  tls:
    - hosts:
        - web.local
      secretName: web-tls

Commandes de vérification rapides :

• kubectl get svc web-svc puis kubectl get endpoints web-svc (les endpoints doivent lister les IP/ports des Pods prêts).
• kubectl describe ingress web-ing pour confirmer ingressClassName, les règles, les événements, et l'adresse.
• kubectl logs deploy/ingress-nginx-controller -n ingress-nginx pour voir l'attachement des règles par le contrôleur.
• Test de trafic HTTP (selon votre exposition) : curl -H "Host: web.local" http://<ADRESSE_INGRESS>/.

Erreur 1 - 404 depuis l'Ingress (backend non résolu)

Symptôme : réponse 404 (souvent « default backend 404 ») quand vous ciblez l'hôte et le chemin attendus.

Pourquoi :

• Le path ne correspond pas (mauvais préfixe, pathType incorrect).
• Le Service pointe sur un targetPort qui ne correspond pas à l'application (ex. app sur 8080 mais Service pointe vers 80).
• Les endpoints du Service sont vides (Pods non prêts, mauvais selector).

Diagnostiquer :

• kubectl get endpoints web-svc - doit contenir au moins une adresse.
• kubectl describe svc web-svc - valider port/targetPort.
• kubectl describe ingress web-ing - vérifier path, pathType, événements.

Correctif sûr :

• Alignez targetPort sur le port où l'application écoute réellement.
• Assurez-vous que selector du Service correspond aux labels des Pods.
• Ajustez path et pathType (souvent Prefix) pour couvrir les routes attendues.

Erreur 2 - 503 Service Unavailable ou « no upstream »

Symptôme : 503 ou messages du contrôleur comme « no upstream » / « no endpoints available for service ».

Pourquoi :

• Aucune instance prête derrière le Service au moment de la requête.
• Readiness probe qui échoue, pods en CrashLoopBackOff ou imagePullBackOff.

Diagnostiquer :

• kubectl get pods -l app=web et kubectl describe pod <pod> - vérifier readiness/liveness et événements.
• kubectl get endpoints web-svc - confirmer qu'il y a des adresses.
• Logs d'app : kubectl logs <pod>.

Correctif sûr :

• Corriger les probes (chemin HTTP, délai initialDelaySeconds, etc.).
• Vérifier l'image Docker, les variables d'environnement et les permissions.
• Attendre un kubectl rollout status deployment/web vert avant de retester l'Ingress.

Erreur 3 - TLS handshake error ou certificat invalide

Symptôme : échec TLS, messages x509 (chaîne invalide) ou événements « Secret not found » pour web-tls.

Pourquoi :

• Secret TLS manquant, mauvais nom, mauvais type (kubernetes.io/tls).
• Le certificat ne couvre pas l'hôte (web.local) ou la clé/chaîne est mal encodée.

Diagnostiquer :

• kubectl get secret web-tls -o yaml - vérifier type: kubernetes.io/tls et la présence de tls.crt / tls.key.
• kubectl describe ingress web-ing - événements liés au TLS.
• openssl s_client -connect <ADRESSE_INGRESS>:443 -servername web.local -showcerts - voir la chaîne présentée.

Correctif sûr :

kubectl create secret tls web-tls --cert=tls.crt --key=tls.key.

• Recréez le secret avec le bon type et les données :
• Assurez la correspondance entre spec.tls.hosts et les SAN/CN du certificat.

Erreur 4 - Ingress non pris en charge par le contrôleur (IngressClass)

Symptôme : l'Ingress n'a pas d'adresse, pas de routing effectif ; journaux indiquant « class not found » ou ressource ignorée.

Pourquoi :

• ingressClassName ne correspond pas au contrôleur installé (ex. nginx).
• Absence d'IngressClass ou annotation alternative manquante.

Diagnostiquer :

• kubectl get ingressclass - vérifier les classes disponibles.
• kubectl describe ingress web-ing - confirmer ingressClassName.
• Journaux du contrôleur Nginx : kubectl logs deploy/ingress-nginx-controller -n ingress-nginx.

Correctif sûr :

• Fixer spec.ingressClassName: nginx si vous utilisez ingress-nginx.
• Alternative (héritage) : metadata.annotations["kubernetes.io/ingress.class"]: "nginx".
• Vérifier que le contrôleur est déployé et en bonne santé dans le bon namespace.

Erreur 5 - Problèmes d'API et de pathType

Symptôme : échec à l'application du manifest, ex. « no matches for kind Ingress in version extensions/v1beta1 » ou « pathType requis ».

Pourquoi :

• Manifests obsolètes (anciennes API), champ pathType manquant en networking.k8s.io/v1.

Diagnostiquer :

• Examiner la version d'API dans le manifest.
• Lire l'erreur d'admission lors de kubectl apply -f ....

Correctif sûr :

• Utiliser apiVersion: networking.k8s.io/v1 et définir pathType à Prefix, Exact ou ImplementationSpecific selon le besoin.
• Vérifier la compatibilité de la ressource avec votre version de Kubernetes.

Checklists pratiques

Avant de tester le trafic :

• kubectl rollout status deployment/<name> - déploiement OK.
• kubectl get endpoints <svc> - endpoints présents.
• kubectl describe ingress <ing> - règles et IngressClass valides, pas d'événements bloquants.
• TLS : secret kubernetes.io/tls existant, hôtes qui correspondent.

Pour le Kubernetes Ingress debugging rapide :

• Logs appli : kubectl logs <pod> et --previous en cas de crash loops.
• Logs contrôleur Nginx : kubectl logs deploy/ingress-nginx-controller -n ingress-nginx.
• Test local : kubectl port-forward (Service ou Pod) pour valider l'application sans Ingress, puis réintroduire l'Ingress.

Intégration avec des sujets connexes (Kubernetes, Nginx, TLS certificates, GitLab CI/CD, Docker) : gardez une ligne claire de cause-à-effet entre build Docker, readiness en cluster, exposé via Service, et routage Ingress. En CI/CD, répétez la même séquence « config → observabilité → test » pour que les échecs soient visibles tôt et traçables.

Conclusion

Les Kubernetes Ingress common errors et leurs correctifs deviennent simples quand l'équipe traite la configuration comme un artefact testable. Restez petit, utilisez des commandes qui prouvent l'état réel, et confirmez le comportement attendu avant d'ajouter d'autres services ou de l'automatisation. Pour la suite, choisissez un service et consignez les commandes exactes pour le construire, l'exécuter, l'inspecter, l'arrêter et le recréer. Comparez le résultat avec vos contraintes autour de Kubernetes, Nginx et des TLS certificates pour que l'implémentation s'intègre naturellement dans votre modèle d'exploitation. Une chaîne fiable rend l'échec visible : logs faciles à trouver, données persistantes préservées, et un comportement local assez proche de la production pour détecter tôt les erreurs.