## Introduction Les ressources Ingress de Kubernetes acheminent le trafic HTTP et HTTPS externe vers les services à l'intérieur d'un cluster. L'objet IngressClass détermine quel contrôleur d'ingress doit implémenter un Ingress particulier. Sans une IngressClass correcte, une ressource Ingress peut être ignorée ou traitée par le mauvais contrôleur, provoquant des défaillances de trafic difficiles à déboguer. Ce guide s'adresse aux développeurs, ingénieurs DevOps et équipes plateforme qui exploitent des clusters Kubernetes. Il se concentre sur les commandes et vérifications nécessaires pour observer l'état d'IngressClass, appliquer des modifications de configuration en toute sécurité, diagnostiquer les défaillances courantes et récupérer après des erreurs de configuration. Plutôt qu'une vue d'ensemble générale, chaque section inclut des commandes kubectl concrètes, des exemples de sortie et des chemins de décision lorsque l'état attendu n'est pas atteint. La sécurité opérationnelle est le fil conducteur : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier les résultats et documenter les étapes de récupération. L'objectif n'est pas seulement de lister des commandes, mais de montrer comment elles s'intègrent dans un flux de travail de dépannage reproductible pour le trafic entrant. ## Inventaire des versions et de l'environnement Avant de modifier quoi que ce soit, collectez la version, la topologie et l'état actuel pertinents. Cette section explique comment identifier quel contrôleur d'ingress est installé, quelles ressources IngressClass existent et comment vérifier la compatibilité. Tout d'abord, vérifiez la version du serveur Kubernetes et la version du client. IngressClass a été introduite dans Kubernetes 1.18 et est devenue plus importante dans la version 1.19 avec l'API networking.k8s.io/v1. Si vous utilisez un cluster plus ancien, le groupe d'API peut être différent. kubectl version --short Exemple de sortie : Client Version: v1.24.0 Server Version: v1.24.0 Ensuite, listez toutes les ressources IngressClass dans le cluster. IngressClass est une ressource à l'échelle du cluster, donc aucun espace de noms n'est nécessaire. kubectl get ingressclass Exemple de sortie : NAME CONTROLLER PARAMETERS AGE nginx k8s.io/ingress-nginx 2d aws ingress.k8s.aws/alb 2d Le champ contrôleur indique quel contrôleur d'ingress traitera les Ingress qui référencent cette classe. Les paramètres peuvent lier une configuration supplémentaire telle qu'une ConfigMap. Si l'IngressClass est marquée comme défaut, elle aura une annotation ingressclass.kubernetes.io/is-default-class: "true" . Pour voir les détails d'une IngressClass spécifique, y compris les annotations et les paramètres : kubectl describe ingressclass nginx Extrait d'exemple : Name: nginx Labels: Annotations: ingressclass.kubernetes.io/is-default-class: true Controller: k8s.io/ingress-nginx Events: Pour confirmer quels pods du contrôleur d'ingress sont en cours d'exécution et dans quel espace de noms : kubectl get pods -A -l app.kubernetes.io/name=ingress-nginx Exemple de sortie : NAMESPACE NAME READY STATUS RESTARTS AGE ingress-nginx ingress-nginx-controller-78f5c7b9d-x2k9d 1/1 Running 0 2d Les prérequis pour utiliser Ingress et IngressClass comprennent : - Un cluster Kubernetes en cours d'exécution, version 1.19 ou ultérieure pour une IngressClass stable. - Un contrôleur d'ingress déployé (nginx-ingress, AWS ALB, Traefik, etc.). - Des autorisations RBAC appropriées pour afficher et modifier les objets Ingress, Service et IngressClass. - Une StorageClass par défaut n'est pas requise, mais Ingress peut référencer des secrets TLS. Gardez le test local minimal. Avant de toucher à un ingress de production, testez avec un manifeste Ingress minimal dans un espace de noms dédié. Par exemple, créez un service echo simple et un Ingress avec une IngressClass spécifique, puis testez avec kubectl port-forward pour vérifier le routage du trafic avant d'exposer un équilibreur de charge cloud. ## Chemin de configuration sûr Cette section explique comment modifier en toute sécurité la configuration liée à IngressClass sans perturber le trafic. Le principe de base est d'effectuer une modification ciblée à la fois et de vérifier son effet avant de passer à la suivante. ### 1. Identifier l'IngressClass actuelle utilisée par un Ingress Une ressource Ingress peut référencer une IngressClass par son nom à l'aide du champ ingressClassName . Si le champ est vide, l'IngressClass par défaut est utilisée (si définie). Vérifiez quelle classe un Ingress existant utilise : kubectl get ingress -n -o jsonpath='{.spec.ingressClassName}' Exemple : kubectl get ingress my-app -n dev -o jsonpath='{.spec.ingressClassName}' La sortie peut être vide si la classe par défaut est utilisée. Vérifiez ensuite la classe par défaut : kubectl get ingressclass -o jsonpath='{.items[?(@.metadata.annotations.ingressclass\.kubernetes\.io/is-default-class=="true")].metadata.name}' ### 2. Changer un Ingress pour utiliser une IngressClass différente Supposons que vous ayez deux contrôleurs d'ingress, nginx et aws, et que vous souhaitiez faire passer un Ingress de la classe par défaut à aws. Tout d'abord, créez un fichier de patch ou utilisez un patch de fusion stratégique. kubectl patch ingress my-app -n dev --type='json' -p='[{"op": "replace", "path": "/spec/ingressClassName", "value":"aws"}]' C'est un changement à faible risque car vous pouvez rapidement revenir en arrière en redéfinissant la valeur précédente. Vérifiez toujours que le contrôleur référencé par la nouvelle classe est en cours d'exécution et en bonne santé avant d'appliquer le patch. ### 3. Définir une IngressClass par défaut Si plusieurs IngressClasses existent et que vous souhaitez définir une classe par défaut pour les nouveaux Ingress, annotez une classe comme défaut. kubectl annotate ingressclass nginx ingressclass.kubernetes.io/is-default-class=true Pour supprimer le statut par défaut d'une autre classe : kubectl annotate ingressclass aws ingressclass.kubernetes.io/is-default-class- Le tiret à la fin supprime la clé d'annotation. Notez qu'une seule IngressClass peut être par défaut à la fois. Si vous définissez une nouvelle classe par défaut alors qu'une autre existe, l'ancienne classe perd automatiquement son statut par défaut. ### 4. Mettre à jour les paramètres d'IngressClass Certains contrôleurs d'ingress prennent en charge une configuration supplémentaire via un objet de paramètres, souvent une ConfigMap. Par exemple, nginx-ingress peut utiliser une ConfigMap pour définir des délais de proxy ou des paramètres SSL. Pour mettre à jour les paramètres en toute sécurité : kubectl edit configmap -n Faites d'abord une sauvegarde : kubectl get configmap -n -o yaml > cm-backup.yaml Après modification, le contrôleur d'ingress rechargera sa configuration (généralement automatiquement). Vérifiez le rechargement en consultant les journaux du contrôleur : kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=20 Recherchez des lignes du type : I0825 10:00:00.123456 7 controller.go:149] "Configuration changes detected, backend reload required" ### 5. Supprimer une IngressClass inutilisée Avant de supprimer, assurez-vous qu'aucune ressource Ingress ne la référence. Listez tous les Ingress avec ingressClassName=aws : kubectl get ingress -A -o json | jq '.items[] | select(.spec.ingressClassName == "aws") | .metadata.name' S'il n'y en a aucun, vous pouvez supprimer l'IngressClass : kubectl delete ingressclass aws La récupération est possible en recréant l'IngressClass à partir d'un manifeste ou d'une exportation YAML précédente. ## Vérification et diagnostic Après avoir apporté des modifications, vous devez vérifier que le trafic circule correctement et diagnostiquer tout problème. Cette section propose une approche structurée. ### Étape 1 : Vérifier l'état de la ressource Ingress Le champ d'état de l'Ingress indique l'adresse attribuée par le contrôleur. Si l'état est vide ou affiche une erreur, le contrôleur peut ne pas traiter l'Ingress. kubectl describe ingress my-app -n dev Regardez la section Événements et le champ Adresse. Exemple d'un Ingress sain : Name: my-app Namespace: dev Address: a1b2c3d4e5f6g7h8.elb.amazonaws.com Default backend: default-http-backend:80 Rules: Host Path Backends ---- ---- -------- example.com / my-service:80 (10.0.0.1:8080) Annotations: Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Sync 10m ingress-controller Scheduled for sync Si l'adresse reste vide, consultez les journaux du contrôleur pour détecter des erreurs. ### Étape 2 : Vérifier la connectivité de bout en bout Utilisez curl depuis l'intérieur du cluster pour tester directement le service et via le contrôleur d'ingress. Tout d'abord, trouvez le nom du pod du contrôleur et exécutez une commande à l'intérieur ou utilisez le transfert de port. kubectl port-forward -n ingress-nginx service/ingress-nginx-controller 8080:80 Dans un autre terminal : curl -H "Host: example.com" http://localhost:8080/ Sortie attendue du service echo : Hello from my-service! Si vous recevez une erreur 404 ou 503, vérifiez si le sélecteur de service correspond aux pods et si le service est joignable. ### Étape 3 : Vérifier les journaux du contrôleur d'ingress kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=50 Messages de journal courants pour une IngressClass manquante : E0825 10:05:00.123456 7 controller.go:114] "Ignoring ingress because of ingress class" ingress="dev/my-app" ingressClass="aws" Cela indique que l'Ingress référence une classe non gérée par ce contrôleur. Soit changez la classe, soit déployez le contrôleur approprié. ### Étape 4 : Valider le DNS et le TLS Si vous utilisez un routage basé sur l'hôte, assurez-vous que l'enregistrement DNS pointe vers l'adresse externe du contrôleur d'ingress. Utilisez dig ou nslookup : dig example.com Vérifiez que l'IP résolue correspond à l'adresse d'état de l'Ingress. Pour le TLS, vérifiez la validité du certificat : echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -dates ### Étape 5 : Déboguer avec les événements pour IngressClass IngressClass elle-même a rarement des événements, mais les ressources associées en ont. kubectl get events -n dev --field-selector involvedObject.name=my-app Cela affiche les événements de synchronisation, les erreurs et les avertissements. ## Modes de défaillance et récupération Cette section décrit les scénarios de défaillance courants liés à IngressClass et comment récupérer. ### Défaillance : Ingress ignoré car aucune IngressClass n'est définie et aucune classe par défaut n'existe Symptôme : L'état de l'Ingress reste vide, aucune erreur sur l'Ingress, mais aucun routage du trafic n'a lieu. Diagnostic : kubectl get ingressclass Si aucune classe n'a l'annotation par défaut, alors un Ingress avec un ingressClassName vide est ignoré. Vérifiez si votre Ingress a ingressClassName défini : kubectl get ingress my-app -n dev -o yaml | grep ingressClassName S'il est vide, définissez la classe explicitement : kubectl patch ingress my-app -n dev -p '{"spec":{"ingressClassName":"nginx"}}' Ou définissez une classe par défaut comme décrit précédemment. ### Défaillance : Mauvais contrôleur sélectionné Symptôme : Le trafic n'atteint pas le backend, les journaux du contrôleur affichent « Ignoring ingress because of ingress class » avec un nom de classe qui ne correspond pas au contrôleur prévu. Diagnostic : kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=20 | grep ingress Récupération : Changez le ingressClassName de l'Ingress vers une classe gérée par le contrôleur en cours d'exécution. Utilisez kubectl patch comme indiqué, ou modifiez le manifeste. ### Défaillance : Paramètres d'IngressClass mal configurés Symptôme : Le rechargement du contrôleur échoue, erreur dans les journaux concernant des paramètres invalides. Diagnostic : Consultez les journaux du contrôleur pour les erreurs d'analyse des paramètres. Pour nginx, cela peut indiquer « invalid ConfigMap » ou « nginx reload failed ». Récupération : Revenez à une version connue et fonctionnelle de la ConfigMap : kubectl apply -f cm-backup.yaml Vérifiez ensuite les journaux du pod du contrôleur pour un rechargement réussi. ### Défaillance : IngressClass supprimée alors que des Ingress la référencent encore Symptôme : Les ressources Ingress affichent un avertissement ou ne sont pas traitées. Diagnostic : kubectl get ingress -A -o json | jq '.items[] | select(.spec.ingressClassName == "missing-class") | [.metadata.name, .metadata.namespace]' Récupération : Recréez l'IngressClass ou mettez à jour les Ingress pour utiliser une classe existante. Pour recréer rapidement avec un manifeste minimal : cat < -n . - [ ] Inspectez les journaux du contrôleur pour détecter des erreurs ou des messages de rechargement. - [ ] Testez la connectivité avec curl/ping et vérifiez la réponse attendue. - [ ] Si le TLS est impliqué, vérifiez la validité du certificat. - [ ] Vérifiez les événements de la ressource Ingress. - [ ] Surveillez pendant quelques minutes pour vous assurer qu'il n'y a pas de défaillances intermittentes. ### Vérification de la récupération Si une modification échoue, revenez à l'état précédent à l'aide de sauvegardes ou de patches inverses. Exécutez ensuite les mêmes étapes de vérification pour confirmer la récupération. Documentez le mode de défaillance et la commande de retour en arrière pour les interventions futures. ## Conclusion Kubernetes IngressClass est un élément petit mais essentiel du routage entrant. Une classe mal configurée peut silencieusement interrompre le trafic ou le router vers le mauvais contrôleur. Les commandes et flux de travail de ce guide fournissent un moyen systématique d'observer, de modifier, de vérifier et de récupérer la configuration liée à IngressClass. Commencez par une vérification à faible risque : listez les IngressClasses, vérifiez la classe par défaut, inspectez un Ingress et suivez une modification unique jusqu'à un routage de trafic réussi. Conservez un enregistrement de l'état actuel, utilisez des sauvegardes et définissez toujours des étapes de récupération avant d'apporter des modifications. En appliquant ces principes, vous réduirez les temps d'arrêt et augmenterez la confiance lors de la gestion d'Ingress dans Kubernetes. Prochaines étapes : choisissez un Ingress de test dans un espace de noms non productif, changez son IngressClass et observez la réaction du contrôleur. Simulez ensuite une classe manquante et entraînez-vous à la récupération. Utilisez la liste de vérification des opérations comme base pour le runbook de votre équipe.