Schéma Kubernetes Ingress : le flux de trafic visualisé

Presque toutes les docs d'architecture en contiennent un : une boîte « Ingress » et une flèche qui pointe directement vers une rangée de Pods. Tout va bien jusqu'au jour où quelqu'un qui débogue une erreur 502 demande où se termine TLS, quel proxy tient la connexion, ou pourquoi une NetworkPolicy bloque un trafic qui « passe par l'Ingress ». Un bon schéma Kubernetes Ingress répond à ces questions avant qu'on les pose. Cet article suit le chemin de la requête saut par saut, relie un manifeste Ingress minimal aux boîtes et aux flèches, liste les erreurs les plus fréquentes en revue et montre comment construire le même diagramme dans Archboard.

Le chemin de la requête, saut par saut

Suivez https://shop.example.com/api/orders du client jusqu'au conteneur :

1. Client → DNS. Le client résout shop.example.com. L'enregistrement (A/AAAA, CNAME ou alias du fournisseur) pointe vers le load balancer cloud, pas vers un nœud.
2. DNS → load balancer cloud. Le client se connecte au load balancer. Dans la plupart des clusters, il existe parce que le contrôleur Ingress est exposé via un Service de type: LoadBalancer ; l'intégration cloud le provisionne pour qu'il transmette vers les node ports ou directement vers les Pods du contrôleur.
3. Load balancer → contrôleur Ingress. Le contrôleur est une charge de travail ordinaire (Deployment ou DaemonSet) qui exécute un reverse proxy comme NGINX, Envoy, HAProxy ou Traefik. C'est lui qui accepte les connexions et relaie les requêtes.
4. Règles Ingress (host/path). Le contrôleur surveille les objets Ingress de sa classe et les transforme en configuration de proxy. L'objet Ingress lui-même ne touche aucun paquet : c'est de la configuration.
5. Service (ClusterIP). Chaque règle désigne un nom et un port de Service. Le Service fournit un nom stable et sélectionne les Pods par label.
6. EndpointSlices. Le control plane enregistre les IP des Pods derrière chaque Service, avec une condition ready pour chacune, dans des objets EndpointSlice. Beaucoup de contrôleurs, dont ingress-nginx, lisent les EndpointSlices et envoient le trafic directement aux IP des Pods plutôt qu'à la ClusterIP. Le Service doit tout de même exister : c'est par lui que le contrôleur trouve ces endpoints.
7. Pods. La requête arrive sur un port de conteneur de l'un des Pods prêts.

Une remarque sur ingress-nginx : le contrôleur communautaire ingress-nginx a été mis à la retraite en mars 2026 et ne reçoit plus de versions, de corrections de bugs ni de correctifs de sécurité. Il reste l'exemple le plus connu ; pour un nouveau cluster, choisissez un contrôleur maintenu ou Gateway API.

Terminaison TLS : choisir une frontière et la dessiner

HTTPS se termine le plus souvent à l'un de ces trois endroits :

Le Secret doit se trouver dans le même namespace que l'Ingress qui le référence. Si vous terminez au load balancer puis rechiffrez vers le contrôleur, dessinez deux segments TLS, pas un seul.

Routage par host ou par chemin

• Le routage par host envoie des noms d'hôte différents vers des backends différents (shop.example.com contre admin.example.com). Dessinez un groupe d'arêtes par host.
• Le routage par chemin découpe un même host selon le chemin d'URL. Avec pathType: Prefix, la correspondance porte sur les éléments du chemin séparés par / : /api correspond à /api/orders mais pas à /apiv2. Exact ne correspond qu'à ce chemin précis ; ImplementationSpecific dépend du contrôleur.
• Quand plusieurs chemins correspondent, le plus long l'emporte. La plupart des Ingress réels combinent règles de host et de chemin.

Où s'applique la NetworkPolicy

Une NetworkPolicy filtre le trafic des Pods en L3/L4, et seulement si le plugin réseau du cluster l'applique. Elle ignore tout des hosts et des chemins et ne s'attache pas à l'objet Ingress. Sur le schéma, le saut qu'elle régit est Pods du contrôleur → Pods applicatifs. Si le namespace applicatif a une politique « default-deny » en entrée, ajoutez-en une qui autorise le trafic depuis le namespace du contrôleur, par exemple avec un namespaceSelector sur kubernetes.io/metadata.name: ingress-nginx. Le saut load balancer → contrôleur relève des règles de pare-feu cloud et des éventuelles politiques du namespace du contrôleur.

Plusieurs classes d'Ingress

Les clusters font souvent tourner plusieurs contrôleurs : public et interne, ou ancien et nouveau pendant une migration. Chaque contrôleur revendique une IngressClass, et chaque Ingress en choisit une via spec.ingressClassName. Une classe peut être marquée par défaut avec l'annotation ingressclass.kubernetes.io/is-default-class: "true". Donnez à chaque contrôleur son propre chemin depuis son propre load balancer et étiquetez chaque Ingress avec sa classe ; sinon, le lecteur supposera qu'un seul proxy gère tout.

Gateway API, en bref

Gateway API (gateway.networking.k8s.io) est l'alternative plus récente, organisée par rôles : une GatewayClass décrit l'implémentation, une Gateway définit les listeners et TLS (en général côté équipe plateforme), et les HTTPRoutes portent les règles de routage (en général côté équipes applicatives). Son routage HTTP de base est GA depuis la v1.0 en 2023. L'API Ingress reste GA et prise en charge, mais elle est gelée : plus de nouvelles fonctionnalités. Le schéma change à peine : la Gateway remplace le listener du contrôleur, les HTTPRoutes remplacent les règles Ingress.

Un Ingress minimal, relié au schéma Kubernetes Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - shop.example.com
      secretName: shop-example-com-tls
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: orders-api
                port:
                  number: 8080
          - path: /
            pathType: Prefix
            backend:
              service:
                name: storefront
                port:
                  number: 80

/api/orders correspond aux deux chemins ; /api est plus long, la requête part donc vers orders-api.

Erreurs fréquentes

• Dessiner l'Ingress comme le proxy. LB → Ingress → Pods se lit comme si l'Ingress était un Pod. Le proxy, c'est le contrôleur ; l'Ingress est la configuration qu'il lit. Placez le contrôleur sur le chemin des données et rattachez-y l'Ingress par une arête en pointillés.
• Oublier le Service. Les backends d'un Ingress référencent des Services, pas des Pods. Même quand le trafic va directement aux IP des Pods, c'est le sélecteur du Service qui casse quand les labels divergent : gardez-le sur le schéma.
• Pas de frontière TLS. Si le schéma ne montre pas où HTTPS se termine, personne ne peut dire si le trafic dans le VPC circule en clair.
• Une NetworkPolicy flottante. Une politique sans arête vers le saut qu'elle régit n'explique rien.

Le construire dans Archboard

Le pack Kubernetes d'Archboard propose des nœuds à part entière, avec ports, pour les objets ci-dessus, dont IngressClass, Gateway et Route, et le pack Network couvre le DNS et le load balancer. La version terminée est le diagramme ci-dessous, et Ouvrir dans Archboard le copie dans votre espace de travail ; /examples/kubernetes-ingress-flow est une esquisse Ingress → Service → Pods plus petite. Pour le construire vous-même :

1. Créez un diagramme et placez un client (une Box ou une Icon du pack Core, ou une Person C4), puis un nœud DNS et un nœud load balancer du pack Network.
2. Ajoutez un cadre Namespace nommé ingress-nginx contenant un Deployment et un Pod pour le contrôleur. L'arête venant du load balancer va vers ce Pod, car c'est lui le proxy.
3. Ajoutez un second cadre Namespace nommé shop. Placez-y l'Ingress, un Secret (shop-example-com-tls) et deux nœuds Service, orders-api et storefront, chacun relié à un Deployment et à un Pod.
4. Reliez les ports le long du chemin des données : client → DNS → load balancer → Pod du contrôleur → chaque Service (étiquetez les arêtes /api et /) → Pods. Étiquetez les arêtes Service → Pod « EndpointSlices » pour montrer comment le trafic atteint les Pods.
5. Reliez le contrôleur à l'Ingress par une arête en pointillés « surveille », et le Secret à l'Ingress.
6. Ajoutez un nœud NetworkPolicy dans le cadre shop et reliez-le au saut contrôleur → application qu'il autorise.
7. Matérialisez la frontière TLS avec un Frame ou une Box du pack Core autour du segment chiffré, en indiquant où elle se termine.
8. Collez le YAML de l'Ingress dans un bloc Markdown sur le canvas, à côté des boîtes qu'il décrit.

L'offre Free autorise 15 nœuds de diagramme par diagramme, plus 150 notes et textes. La construction complète ci-dessus en utilise 18, donc retirez les trois nœuds Deployment, y compris celui du contrôleur, et reliez directement les Services aux Pods : le chemin du trafic reste intact. Exportez en SVG ou PNG (avec filigrane sur Free), ou en JSON structuré à conserver à côté de vos manifestes. Pour la vue d'ensemble du cluster, voyez /examples/kubernetes-microservices et Archboard pour Kubernetes. La référence officielle est la documentation Kubernetes sur Ingress.

FAQ

L'Ingress doit-il être dessiné dans le namespace de l'application ? Oui. Ingress est un objet namespacé qui ne peut référencer que des Services et des Secrets TLS de son propre namespace. Le contrôleur tourne généralement dans un namespace à part.

Le trafic passe-t-il par la ClusterIP du Service ? Cela dépend du contrôleur. Beaucoup relaient directement vers les IP des Pods à partir des EndpointSlices. Dessinez quand même le Service et étiquetez l'arête.

Ingress ou Gateway API pour un nouveau cluster ? Gateway API si votre contrôleur la prend en charge : l'API Ingress est gelée. La méthode de schématisation reste la même.

Commencez gratuitement — un siège, sans carte bancaire