Implémenter les Ingress dans tes projets Kubernetes
Huit services, huit IP publiques : le classique. Comment mutualiser ta porte d'entrée Kubernetes en 2026, sans ingress-nginx.
Huit services exposés, huit adresses IP publiques, huit load balancers facturés. C'est le schéma classique d'un cluster qui a grandi sans jamais mutualiser sa porte d'entrée.
Un Ingress règle ce problème en deux manifests. Voici comment le poser proprement en 2026, sans hériter des pièges du contrôleur historique.
Ce que l'Ingress mutualise vraiment
Un Ingress est une règle de routage L7 : un nom d'hôte et un chemin pointent vers un Service Kubernetes. Le contrôleur lit ces règles et les traduit en configuration nginx, Envoy, HAProxy ou Traefik.
Conséquence directe : une seule IP publique, un seul certificat par domaine, et des routes versionnées dans Git au lieu d'un vhost édité à la main sur un serveur.
| Sans Ingress | Avec Ingress |
|---|---|
| Un load balancer par Service exposé (10 à 25 € par mois chacun) | Un contrôleur unique, Services en ClusterIP |
| TLS géré service par service | Terminaison TLS centralisée |
| Nouveau service = nouvelle IP + nouveau DNS | Nouveau service = une règle de plus |
| Aucune vue d'ensemble du trafic entrant | kubectl get ingress liste toutes les routes |
Sur un cluster de préprod à huit services, passer de huit Services LoadBalancer à un contrôleur unique fait tomber la facture réseau sous les 20 € par mois. Le gain réel reste ailleurs : tu vois enfin où part chaque requête.
Ce qu'un Ingress ne fait pas : pas de TCP ou UDP brut (il faut un Service LoadBalancer ou un CRD dédié), pas de mTLS entre pods, pas de WAF. Pour ces besoins, c'est service mesh ou passerelle spécialisée.
Les quatre objets à connaître avant d'écrire un manifest
Un Ingress ne vit jamais seul. Il s'appuie sur quatre ressources, et une seule manquante suffit à tout bloquer.
- IngressClass : désigne le contrôleur à utiliser (
nginx,traefik,cilium). Un cluster peut en héberger plusieurs en parallèle. - Ingress : les règles de routage, host et paths.
- Service : la cible des règles. Un
ClusterIPsuffit, le contrôleur parle au Service et jamais directement aux pods. - Secret de type
kubernetes.io/tls: la paire certificat et clé privée, montée par le contrôleur.
Détail qui coûte une heure : sans ingressClassName ni annotation kubernetes.io/ingress.class, la ressource est ignorée en silence si le contrôleur n'est pas celui par défaut. kubectl describe ingress affiche alors les règles, mais aucune adresse en face.
Le manifest minimal qui fonctionne
Commence par le Service, en ClusterIP. C'est lui que l'Ingress cible :
apiVersion: v1
kind: Service
metadata:
name: api
namespace: prod
spec:
selector:
app: api
ports:
- port: 80
targetPort: 8080Puis l'Ingress, avec le host, le chemin et le secret TLS :
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: api
namespace: prod
spec:
ingressClassName: nginx
rules:
- host: api.tonprojet.fr
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: api
port:
number: 80
tls:
- hosts:
- api.tonprojet.fr
secretName: api-tonprojet-fr-tlspathType: Prefix matche /api et tout ce qui suit, donc /api/v1/users. Exact ne matche que la chaîne complète, sans slash final. ImplementationSpecific laisse le contrôleur décider du comportement et rend ton manifest dépendant du moteur : à éviter.
Contrôle en deux commandes : kubectl get ingress api -n prod -o wide doit afficher une adresse dans la colonne ADDRESS. Si elle reste vide après trente secondes, le contrôleur ne voit pas la ressource, souvent à cause d'un ingressClassName faux ou d'un namespace absent du périmètre surveillé.
Installer un contrôleur en 2026 : le choix qui a changé
Le point dur de cette année : ingress-nginx est retiré depuis mars 2026. Plus de correctifs, plus de failles corrigées, dépôt en lecture seule. Un cluster neuf qui l'installe aujourd'hui démarre sur un composant mort.
Trois options tiennent la route : Traefik, pour ses CRD et son intégration cert-manager native ; Cilium, pour son data plane eBPF qui couvre Ingress et Gateway API ; Envoy Gateway, si tu pars directement sur Gateway API.
Pour un cluster existant encore sur ingress-nginx, la priorité n'est pas de tout migrer ce week-end, mais d'inventorier ce que tu utilises réellement. Cette commande sort le classement des annotations en place :
kubectl get ingress -A -o json \
| jq '[.items[].metadata.annotations // {} | keys[]] | group_by(.) | map({annotation: .[0], usages: length}) | sort_by(-.usages)'Ce sont ces annotations qui décideront de l'effort de migration, pas le nombre d'Ingress. Un cluster avec quarante routes et trois annotations se migre en une journée. Un cluster avec configuration-snippet partout demande une réécriture manuelle.
TLS automatique avec cert-manager
cert-manager supprime la gestion manuelle des certificats. Un ClusterIssuer, une annotation, et le renouvellement se fait seul.
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: admin@tonprojet.fr
privateKeySecretRef:
name: letsencrypt-prod-key
solvers:
- http01:
ingress:
ingressClassName: nginxCôté Ingress, deux lignes suffisent, l'annotation et le bloc TLS déjà présent :
metadata:
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prodcert-manager crée le Secret api-tonprojet-fr-tls et le renouvelle trente jours avant expiration. kubectl get certificate -n prod doit afficher READY=True en moins de deux minutes.
Le piège classique : lancer l'émission avant que le DNS pointe vers l'IP du contrôleur. Let's Encrypt valide en HTTP-01, échoue, et après cinq échecs te bloque une heure. dig +short api.tonprojet.fr doit renvoyer l'IP de l'Ingress avant le premier apply.
Les trois réglages qui évitent 90 % des incidents
Les annotations sont le point faible de l'Ingress : non typées, non validées, et silencieuses quand elles sont fausses. Trois d'entre elles reviennent dans presque tous les tickets.
| Annotation | Défaut | Symptôme si tu l'oublies |
|---|---|---|
proxy-body-size | 1m | 413 sur tout upload de plus d'un mégaoctet |
proxy-read-timeout | 60s | 504 sur un import ou un export long |
rewrite-target + use-regex | aucun | 404 côté backend, le préfixe de route n'est pas retiré |
Cas concret : un import CSV de 12 Mo renvoyait 413 sans aucune trace dans les logs applicatifs, puisque la requête n'atteignait jamais le conteneur. Une annotation nginx.ingress.kubernetes.io/proxy-body-size: "20m" a suffi, et le passage à "0" dans le ConfigMap du contrôleur supprime la limite pour tout le cluster quand le besoin est général.
Pour un déploiement progressif, les annotations canary restent efficaces : nginx.ingress.kubernetes.io/canary: "true" et canary-weight: "10" sur un second Ingress envoient 10 % du trafic vers la nouvelle version. Gateway API fait mieux avec un poids natif dans backendRefs, sans second objet à maintenir.
La checklist que je passe avant chaque apply
Six contrôles, deux minutes, et la moitié des incidents d'Ingress disparaît avant la mise en production.
- Le DNS résout vers l'IP du contrôleur :
dig +short api.tonprojet.fr. - Le Service a des endpoints non vides :
kubectl get endpoints api -n prod. - Le
targetPortdu Service correspond au port réellement écouté par le conteneur. - Le Secret TLS existe et couvre exactement le host déclaré.
- Le
pathTypeest explicite, jamaisImplementationSpecificpar défaut. - La ressource porte un
ingressClassNamecorrespondant au contrôleur installé.
Puis un test qui vaut tous les describe : curl -sI https://api.tonprojet.fr/api/health doit renvoyer un code 2xx et un certificat valide. Pour vérifier la date d'expiration réellement servie, openssl s_client -connect api.tonprojet.fr:443 -servername api.tonprojet.fr 2>/dev/null | openssl x509 -noout -dates attrape un Secret périmé que le contrôleur continue de servir.
Ingress ou Gateway API en 2026 ?
Avis tranché : Ingress reste le bon choix pour du routage host, path et TLS. L'API n'est pas dépréciée, elle est gelée côté fonctionnalités. Seul le contrôleur ingress-nginx est retiré, et c'est cette nuance qui évite de migrer dans la panique.
Passe à Gateway API dès que tu as besoin de routage par en-tête, de partage d'une passerelle entre équipes avec RBAC par route, de HTTP/2 ou gRPC explicite, ou de split de trafic pondéré natif.
| Ingress | Gateway API |
|---|---|
IngressClass | GatewayClass + Gateway |
Règles host / path | HTTPRoute avec matches |
Bloc tls | listeners du Gateway |
| Annotations canary | weight dans backendRefs |
rewrite-target | Filtre URLRewrite |
La migration est outillée depuis mars 2026 : ingress2gateway 1.0 traduit les manifests et plus de trente annotations ingress-nginx. Tu lui donnes un namespace ou un fichier, il sort du Gateway API applicable :
ingress2gateway print --namespace prod --providers=ingress-nginx > gwapi.yamlRelis les warnings produits par l'outil : chaque annotation non traduite y apparaît. C'est exactement là que se cachent les régressions de comportement, bien plus que dans le YAML généré.
FAQ
Un Ingress par service ou un seul pour tout ?
Un par service, dans son namespace. Tu gardes l'ownership par équipe et un kubectl delete ne coupe pas les voisins. Regrouper toutes les routes dans un fichier unique finit toujours en conflit de merge.
Pourquoi un 404 alors que le pod tourne ?
Trois causes dominent : le host de l'Ingress ne correspond pas à l'en-tête Host reçu, le pathType ne matche pas la requête, ou le Service pointe vers un port inexistant. kubectl get endpoints api -n prod révèle immédiatement un sélecteur cassé avec une liste vide.
LoadBalancer ou NodePort pour exposer le contrôleur ?
LoadBalancer en cloud managé, NodePort uniquement en bare-metal derrière un reverse proxy. Sur un VPS sans implémentation de load balancer, un Service LoadBalancer reste en Pending indéfiniment.
Peut-on faire du WebSocket à travers un Ingress ?
Oui, à condition d'allonger le timeout de lecture. proxy-read-timeout: "3600" évite la coupure à soixante secondes qui ressemble à un bug applicatif alors qu'elle vient du proxy.
Si tu montes ta première brique réseau Kubernetes, commence par les fondamentaux de Kubernetes, puis compare avec l'approche reverse proxy nginx classique : les concepts se recoupent, la mécanique de découverte de services change tout.