Kubernetes Ingress Class : Commandes de base et exemples pratiques

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            <none>       2d
aws       ingress.k8s.aws/alb             <none>       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:       <none>
Annotations:  ingressclass.kubernetes.io/is-default-class: true
Controller:   k8s.io/ingress-nginx
Events:       <none>

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 <nom-ingress> -n <espace-de-noms> -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 <nom-configmap> -n <espace-de-noms>

Faites d'abord une sauvegarde :

kubectl get configmap <nom-configmap> -n <espace-de-noms> -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:  <none>
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 <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
spec:
  controller: k8s.io/ingress-nginx
EOF

Défaillance : RBAC empêche le contrôleur de lire IngressClass

Symptôme : Les journaux du contrôleur affichent des erreurs forbidden lors de la tentative de lister les IngressClass. Diagnostic :

kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=20 | grep forbidden

Récupération : Assurez-vous que le compte de service du contrôleur dispose des autorisations RBAC pour get, list, watch IngressClass. Vérifiez le ClusterRole et le ClusterRoleBinding du contrôleur d'ingress.

kubectl describe clusterrole ingress-nginx

Si manquant, ajoutez une règle :

- apiGroups: ["networking.k8s.io"]
  resources: ["ingressclasses"]
  verbs: ["get", "list", "watch"]

Défaillance : Conflit d'IngressClass par défaut

Symptôme : Les Ingress sont routés de manière imprévisible, ou les journaux des contrôleurs signalent des conflits. Diagnostic :

kubectl get ingressclass -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.ingressclass\.kubernetes\.io/is-default-class}{"\n"}{end}'

Si plus d'une classe affiche true, supprimez l'annotation par défaut de toutes sauf celle que vous souhaitez conserver.

Liste de vérification des opérations

Utilisez cette liste avant et après avoir apporté des modifications à IngressClass ou aux ressources Ingress associées.

Liste de vérification avant modification

• [ ] Vérifiez que la version du cluster est 1.19+ pour une API IngressClass stable.
• [ ] Listez toutes les IngressClasses et identifiez la classe par défaut : kubectl get ingressclass.
• [ ] Confirmez que le contrôleur d'ingress pour la classe cible est en cours d'exécution et en bonne santé.
• [ ] Pour un Ingress spécifique, vérifiez le ingressClassName actuel et notez-le.
• [ ] Sauvegardez toute ConfigMap ou tout manifeste Ingress qui sera modifié.
• [ ] Assurez-vous d'avoir les autorisations de modification et un plan de retour en arrière.

Liste de vérification pour l'exécution des modifications

• [ ] Appliquez une modification à la fois (par exemple, patcher un Ingress, mettre à jour une ConfigMap).
• [ ] Utilisez des commandes ciblées, pas des suppressions larges.
• [ ] Si vous changez la classe par défaut, vérifiez qu'une seule classe possède l'annotation par défaut après coup.
• [ ] Enregistrez l'horodatage et la commande exacte utilisée.

Liste de vérification après modification

• [ ] Vérifiez que l'adresse d'état de l'Ingress est renseignée : kubectl get ingress <nom> -n <ns>.
• [ ] 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.