Ingress Kubernetes : exposer vos applications HTTP/HTTPS

Un Ingress expose vos Services HTTP/HTTPS vers l'extérieur du cluster avec du routage par domaine et chemin. Au lieu de créer un LoadBalancer par application, vous centralisez l'entrée du trafic sur un point unique, avec gestion TLS intégrée. Ce guide vous montre comment configurer un Ingress fonctionnel.

ingress-nginx archivé depuis le 24 mars 2026

Le contrôleur communautaire ingress-nginx ne reçoit plus aucun correctif de sécurité. Ce guide utilise désormais Traefik. L'API Ingress, elle, n'est pas concernée : détail et conduite à tenir plus bas.

Une précision s'impose, parce que les deux nouvelles se mélangent facilement. L'API Ingress, la ressource elle-même, reste stable et supportée : ce n'est pas elle qui s'arrête. Elle est en revanche gelée depuis 2022, donc sans nouvelles fonctionnalités. Dès que vous avez besoin de routage gRPC, de répartition de trafic pondérée, de sélection par en-tête ou de mTLS, c'est vers Gateway API que Kubernetes vous oriente.

Ce que vous allez apprendre

• Comprendre le rôle d'un Ingress et d'un Ingress Controller
• Créer un Ingress avec ingressClassName
• Configurer le routage par domaine et par chemin
• Activer TLS avec cert-manager
• Débugger les erreurs courantes

Ingress vs Gateway API : que choisir ?

Les deux API coexistent dans le même cluster et peuvent être servies par le même contrôleur, elles ne s'excluent pas. La différence tient au périmètre couvert par la spécification : tout ce qu'Ingress ne sait pas exprimer (redirection, réécriture, découpage de trafic) passe par des annotations propriétaires, alors que Gateway API le décrit dans ses propres ressources. Le tableau suivant résume les critères qui pèsent au moment du choix.

Critère	Ingress	Gateway API
Statut	Stable, gelé (pas d'évolution)	Stable, en développement actif
Cas d'usage	HTTP/HTTPS simple, routage host/path	HTTP/HTTPS avancé, gRPC, TCP, traffic splitting
Portabilité	Dépend fortement des annotations du contrôleur	Plus standardisé
Recommandation Kubernetes	Maintenu pour compatibilité	Recommandé pour nouveaux projets

Glissez pour voir

En résumé : Ingress reste valide pour les cas simples. Pour du routage avancé ou un nouveau projet, préférez Gateway API.

Pourquoi ingress-nginx s'est arrêté, et ce que vous devez faire

Le projet communautaire ingress-nginx, longtemps le contrôleur de référence, a été retiré le 24 mars 2026. Son dépôt GitHub est en lecture seule : plus aucune version, plus aucun correctif de faille. La cause tient en deux mots, une charge de maintenance devenue insoutenable et une accumulation de vulnérabilités liées aux annotations snippets.

Cinq jours avant l'arrêt, une dernière faille critique a été publiée : CVE-2026-4342, de score CVSS 8.8. Une combinaison d'annotations Ingress injecte de la configuration dans nginx, ce qui permet l'exécution de code arbitraire dans le contrôleur et la divulgation des Secrets auxquels il accède, soit ceux de tout le cluster dans une installation par défaut. Le droit de créer une simple ressource Ingress suffit à l'exploiter. Elle est corrigée dans les versions 1.13.9, 1.14.5 et 1.15.1, les dernières que ce projet publiera : appliquez-en une sans attendre si vous l'exploitez encore, car les failles suivantes ne seront jamais corrigées.

Trois conduites à tenir selon votre situation :

Situation	Ce qu'il faut faire
Cluster existant sous ingress-nginx	Appliquer un des trois correctifs, puis planifier la migration. Les exemples Helm ingress-nginx/ingress-nginx continuent de fonctionner, sans aucun correctif de sécurité.
Nouveau cluster	Préférer Gateway API, ou un contrôleur Ingress activement maintenu : Traefik, Contour, HAProxy Ingress.
Besoin d'un support commercial	Le NGINX Ingress Controller de NGINX Inc. est un produit différent du projet communautaire ingress-nginx, et il est maintenu. La confusion de noms est la principale source d'erreur ici.

Glissez pour voir

Sources : Ingress NGINX Retirement, SIG Network et l'advisory CVE-2026-4342.

Comment fonctionne un Ingress ?

Le trafic n'entre jamais dans un objet Ingress : il entre dans le Service du contrôleur, généralement de type LoadBalancer ou NodePort. Le contrôleur surveille en permanence les objets Ingress de tous les namespaces et régénère sa propre configuration à chaque changement, en quelques secondes. Le routage se fait ensuite en une seule traversée, sans rebond par l'API Kubernetes.

1. L'utilisateur envoie une requête vers https://mon-app.example.com

2. L'Ingress Controller intercepte la requête et consulte les règles définies dans les objets Ingress

3. Le Controller route vers le Service correspondant au host et au path

4. Le Service distribue aux Pods disponibles

5. La réponse remonte via le même chemin

Sans Ingress Controller, rien ne se passe

L'objet Ingress est juste une configuration. C'est l'Ingress Controller qui interprète ces règles et fait le routage réel. Sans Controller déployé, vos Ingress n'ont aucun effet.

Prérequis

• Cluster Kubernetes fonctionnel. Sur kind, le cluster de cette formation, il demande deux réglages précis : voir juste en dessous.
• kubectl configuré pour accéder au cluster
• Un Ingress Controller installé (voir section suivante)
• DNS ou /etc/hosts pour résoudre vos domaines de test

Vérifiez votre cluster :

kubectl cluster-info

Installer un Ingress Controller

Un cluster peut héberger plusieurs contrôleurs en parallèle, chacun déclarant sa propre IngressClass. C'est ce qui rend une migration progressive possible : les Ingress migrés changent de ingressClassName, les autres continuent de fonctionner. Le tableau ci-dessous donne l'état de maintenance de chaque projet, critère décisif depuis l'archivage de ingress-nginx.

Controller	Statut 2026	Points forts
ingress-nginx (projet communautaire)	❌ Archivé depuis le 24 mars 2026	Le plus répandu historiquement, beaucoup d'exemples, mais plus de correctifs CVE
NGINX Ingress Controller (NGINX Inc., commercial / open source distinct)	✅ Activement maintenu	Produit F5/NGINX, à ne pas confondre avec ingress-nginx
Traefik	✅ Activement maintenu	Léger, config dynamique, bon pour microservices, supporte aussi Gateway API
HAProxy Ingress	✅ Activement maintenu	Performant, adapté aux charges élevées
Contour	✅ Activement maintenu	Basé sur Envoy, moderne, supporte Gateway API

Glissez pour voir

Installation avec Helm (Traefik recommandé en 2026)

Les exemples de ce guide utilisent Traefik comme contrôleur de référence : activement maintenu, installable en une commande Helm, et il supporte aussi Gateway API, ce qui rend la migration ultérieure cohérente.

helm repo add traefik https://traefik.github.io/charts
helm repo update

helm install my-ingress traefik/traefik \
  --namespace traefik \
  --create-namespace

Vérifiez l'installation :

kubectl get pods -n traefik
kubectl get svc -n traefik
kubectl get ingressclass

La sortie de kubectl get ingressclass doit afficher traefik, c'est le nom à utiliser dans ingressClassName plus loin.

Sur kind : deux réglages, et deux pièges

Un cluster kind neuf n'a ni contrôleur Ingress ni répartiteur de charge. kubectl get ingressclass y répond No resources found, et c'est normal : contrairement à k3d, kind ne préinstalle rien. Il faut donc préparer le cluster avant de le créer, puis installer le contrôleur.

Le fichier de configuration fait deux choses : il ouvre les ports 80 et 443 vers votre poste, et il marque le nœud pour que le contrôleur sache où se placer.

kind-ingress.yaml

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    labels:
      ingress-ready: "true"
    extraPortMappings:
      - containerPort: 80
        hostPort: 8080
        protocol: TCP
      - containerPort: 443
        hostPort: 8443
        protocol: TCP

kind create cluster --name doc-ingress \
  --image kindest/node:v1.37.0 --config kind-ingress.yaml

Deux pièges qui bloquent, et leurs messages

Le libellé se pose avec labels:, pas avec kubeadmConfigPatches. La recette la plus répandue passe par nodeRegistration.kubeletExtraArgs. Sur un nœud 1.37, kubeadm la refuse :

error: your configuration file uses an old API spec: "kubeadm.k8s.io/v1beta3"
(kind: "ClusterConfiguration")

Le champ labels: du nœud obtient le même résultat sans passer par kubeadm.

Le nodeSelector de Helm se passe en --set-string. Avec --set, Helm type true en booléen, et l'API refuse le patch :

Error: INSTALLATION FAILED: failed to create typed patch object
.spec.template.spec.nodeSelector.ingress-ready: expected string, got true

Installez ensuite Traefik en lui demandant trois choses : se poser sur le nœud marqué, tolérer le taint du control plane, et écouter sur les ports du nœud.

helm repo add traefik https://traefik.github.io/charts
helm repo update

helm install traefik traefik/traefik \
  --namespace traefik --create-namespace \
  --set service.type=ClusterIP \
  --set-string nodeSelector.ingress-ready=true \
  --set tolerations[0].key=node-role.kubernetes.io/control-plane \
  --set tolerations[0].operator=Exists \
  --set tolerations[0].effect=NoSchedule \
  --set ports.web.hostPort=80 \
  --set ports.websecure.hostPort=443 \
  --wait

Sortie

traefik with docker.io/traefik:v3.7.13 has been deployed successfully on traefik namespace!

kubectl get ingressclass

Sortie

NAME                CONTROLLER                      PARAMETERS   AGE
traefik (default)   traefik.io/ingress-controller   <none>       28s

Votre Ingress est désormais joignable sur http://localhost:8080, le port que le fichier de configuration a mis en correspondance avec le port 80 du nœud.

Créer votre premier Ingress

Un Ingress ne pointe pas vers des Pods mais vers un Service, qui doit donc exister avant lui. Créer l'Ingress en premier ne produit aucune erreur : la ressource est acceptée, le contrôleur renvoie simplement du 503 tant que le backend est absent. On déploie donc l'application, puis le Service, puis l'Ingress.

Préparer l'application et le Service

Le manifeste ci-dessous crée le Deployment et son Service dans le même fichier, séparés par ---. Le port du Service (80) est celui que l'Ingress référencera ; le targetPort est celui qu'écoute le conteneur.

webapp-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: webapp
  template:
    metadata:
      labels:
        app: webapp
    spec:
      containers:
      - name: webapp
        image: nginx:1.25.4@sha256:9ff236ed47fe39cf1f0acf349d0e5137f8b8a6fd0b46e5117a401010e56222e1
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: webapp-service
spec:
  selector:
    app: webapp
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80

kubectl apply -f webapp-deployment.yaml

Créer l'Ingress

La règle ci-dessous ne répond qu'aux requêtes portant l'en-tête Host: webapp.local : une requête sur l'IP nue tombera en 404.

webapp-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: webapp-ingress
spec:
  ingressClassName: traefik
  rules:
  - host: webapp.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: webapp-service
            port:
              number: 80

ingressClassName est obligatoire

Déclarez toujours ingressClassName pour dire quel contrôleur doit gérer cet Ingress. Sans cette valeur, le comportement dépend de la configuration du cluster : autrement dit, il n'est pas prévisible.

kubectl apply -f webapp-ingress.yaml

Tester l'accès

Le test suppose deux choses : connaître l'adresse d'écoute du contrôleur et faire correspondre le nom de domaine à cette adresse, puisque c'est lui qui déclenche la règle.

Récupérez l'adresse du Controller :

kind

Avec le extraPortMappings posé plus haut, le contrôleur écoute sur localhost:8080, sans Service de type LoadBalancer et sans port-forward.

kubectl get ingress

Sortie

NAME             CLASS     HOSTS          ADDRESS   PORTS   AGE
webapp-ingress   traefik   webapp.local             80      13s

La colonne ADDRESS reste vide, et ce n'est pas une panne. Elle n'est remplie que par un contrôleur adossé à un LoadBalancer, ce que kind ne fournit pas. Le routage fonctionne quand même, par les ports du nœud.

k3d / k3s

Traefik est exposé par k3d via le LoadBalancer intégré, sur les ports 80 et 443 du host.

# Vérifier le Service Traefik (namespace kube-system pour k3s)
kubectl get svc -n kube-system traefik

L'IP utile est 127.0.0.1 (le LB k3d le forward localement) ou l'IP du nœud (172.21.x.x).

Helm Traefik dédié

kubectl get svc -n traefik my-ingress

Récupérez l'IP/EXTERNAL-IP. Sur un cluster sans LoadBalancer cloud, utilisez kubectl port-forward ou exposez via un NodePort.

Minikube

minikube ip

Configurez la résolution DNS (fichier /etc/hosts) :

# Remplacez par l'IP réelle de votre Controller
echo "127.0.0.1 webapp.local" | sudo tee -a /etc/hosts

L'adresse dépend de votre environnement

127.0.0.1 ne fonctionne que si le contrôleur écoute réellement sur votre poste : c'est le cas avec kind et extraPortMappings, ou avec le répartiteur intégré de k3d. Ailleurs, ce sera l'IP de Minikube, celle d'une VM, ou l'EXTERNAL-IP d'un LoadBalancer cloud.

Sur le cluster kind préparé plus haut, le Host peut aussi se passer en en-tête, ce qui évite de toucher à /etc/hosts :

curl -H 'Host: webapp.local' http://localhost:8080

Deux résultats valent une démonstration. Avec le bon Host, la page répond ; sans lui, le contrôleur ne trouve aucune règle et rend un 404. C'est la preuve directe que le routage se fait bien sur le nom de domaine, et non sur le port.

Mesuré sur le cluster kind de cette formation

curl -H 'Host: webapp.local' http://localhost:8080   ->  HTTP 200
curl                         http://localhost:8080   ->  HTTP 404

Le port à interroger est 8080, pas 80

C'est l'erreur qui fait croire à une panne d'Ingress alors que tout fonctionne. Le fichier de configuration met en correspondance le port 8080 de votre poste avec le port 80 du nœud, et kind ne publie rien d'autre. La commande qui le prouve, une fois le cluster créé :

docker port doc-ingress-control-plane

Sortie

80/tcp -> 0.0.0.0:8080
443/tcp -> 0.0.0.0:8443
6443/tcp -> 127.0.0.1:32933

Un curl http://127.0.0.1 sans port, ou un curl http://webapp.local après avoir renseigné /etc/hosts, visent donc le port 80 de votre poste, que rien ne relie au cluster. Si une réponse arrive quand même, elle vient d'autre chose qui tourne sur votre machine, et elle vous induira en erreur. La ligne /etc/hosts reste utile, mais le port s'écrit :

curl http://webapp.local:8080

Routage multi-domaines

Un même objet Ingress accepte plusieurs entrées host, chacune avec ses propres chemins. Regrouper les domaines dans une seule ressource garde la configuration lisible, mais tous les domaines partagent alors le même cycle de vie : supprimer l'Ingress coupe tout d'un coup. Sur des applications gérées par des équipes différentes, préférez un Ingress par application, ils peuvent viser le même contrôleur sans conflit.

multi-domain-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: multi-app-ingress
spec:
  ingressClassName: traefik
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: webapp-service
            port:
              number: 80
  - host: api.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80

Routage par chemin

Sous un même domaine, plusieurs chemins peuvent viser des Services distincts, ce qui permet d'exposer une API et son interface web sans sous-domaine dédié. Le chemin est transmis tel quel au backend : /api/users arrive en /api/users sur api-service, sauf réécriture explicite. Le path: / sert de règle par défaut pour tout ce qui ne correspond à aucun préfixe plus long.

path-routing-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: path-routing
spec:
  ingressClassName: traefik
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80
      - path: /
        pathType: Prefix
        backend:
          service:
            name: frontend-service
            port:
              number: 80

Le champ pathType décide de ce que « correspondre » veut dire, et deux valeurs couvrent presque tous les cas. Prefix fait correspondre /api à /api, /api/ et /api/users : c'est celle qu'on veut presque toujours. Exact ne fait correspondre que /api, au caractère près. L'ordre dans lequel vous écrivez les chemins n'a aucune importance : Kubernetes retient le préfixe le plus spécifique, ce qui permet de laisser path: / en dernier filet sans qu'il capte le trafic des autres règles.

Configurer TLS avec cert-manager

Le champ tls d'un Ingress attend un Secret de type kubernetes.io/tls déjà présent dans le même namespace que l'Ingress. cert-manager automatise la création et le renouvellement de ce Secret : il observe les Ingress annotés, demande le certificat à l'autorité configurée et renouvelle par défaut à deux tiers de la durée de vie, soit environ 30 jours avant l'expiration pour Let's Encrypt.

Installer cert-manager

Le guide dédié cert-manager détaille l'installation, les Issuer et les certificats Let's Encrypt. Installation rapide :

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.20.3/cert-manager.yaml

Vérifiez l'installation :

kubectl get pods -n cert-manager

Créer un ClusterIssuer pour Let's Encrypt

Un ClusterIssuer est non namespacé : il sert tous les namespaces du cluster, contrairement à un Issuer. L'email reçoit les avertissements d'expiration de Let's Encrypt et le privateKeySecretRef désigne le Secret où cert-manager stocke la clé du compte ACME, à ne pas confondre avec le certificat lui-même.

cluster-issuer.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: votre-email@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          ingressClassName: traefik

kubectl apply -f cluster-issuer.yaml

Configurer l'Ingress avec TLS

Le secretName désigne un Secret que vous n'avez pas besoin de créer : cert-manager le remplit après validation du challenge. Le nom de domaine du bloc tls doit être identique à celui de la règle rules, sinon le certificat émis ne couvrira pas le trafic servi.

secure-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: secure-ingress
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: traefik
  tls:
  - hosts:
    - monsite.example.com
    secretName: monsite-tls
  rules:
  - host: monsite.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: webapp-service
            port:
              number: 80

Conditions pour que TLS fonctionne

L'annotation cert-manager.io/cluster-issuer déclenche la demande de certificat, mais l'émission n'aboutit qu'à trois conditions, qui doivent être toutes remplies en même temps :

• Le domaine résout vers l'adresse de votre contrôleur d'entrée
• L'Ingress est joignable depuis Internet, condition du défi HTTP01
• Le défi ACME aboutit réellement, et pas seulement en apparence

En local sans DNS public, utilisez des certificats auto-signés ou un Issuer de test.

kubectl apply -f secure-ingress.yaml

# Vérifier le certificat
kubectl get certificate
kubectl describe certificate monsite-tls

Annotations courantes (par contrôleur)

Tout ce que la spécification Ingress ne couvre pas, redirection HTTPS, filtrage d'IP, limites de taille, se règle par des annotations interprétées par le contrôleur. Une annotation inconnue est ignorée en silence : aucune erreur à l'apply, la fonctionnalité ne s'applique simplement jamais. C'est le premier réflexe de diagnostic quand un comportement attendu ne se produit pas après une migration de contrôleur.

Les annotations sont la principale dette de portabilité d'Ingress : chaque contrôleur a son préfixe, traefik.ingress.kubernetes.io/*, nginx.ingress.kubernetes.io/*, haproxy.org/*. Changer de contrôleur oblige donc à toutes les réécrire, et c'est précisément ce que Gateway API corrige en décrivant ces comportements dans l'API elle-même. Les exemples ci-dessous montrent le même besoin sous Traefik, le contrôleur de ce guide, et sous ingress-nginx, que vous croiserez encore sur des clusters existants.

Redirection HTTPS

Sans cette redirection, le site reste joignable en HTTP clair même quand le bloc tls est présent : activer TLS n'interdit pas le port 80.

Traefik

Avec Traefik, la redirection HTTPS se configure via un Middleware (CRD Traefik) référencé par annotation :

# Middleware (à créer une fois)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: redirect-https
spec:
  redirectScheme:
    scheme: https
    permanent: true
---
# Ingress référençant le middleware
metadata:
  annotations:
    traefik.ingress.kubernetes.io/router.middlewares: default-redirect-https@kubernetescrd

ingress-nginx (legacy)

metadata:
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"

Restriction par IP

Le filtrage s'applique à l'IP source vue par le contrôleur : derrière un load balancer cloud qui ne préserve pas l'adresse d'origine, toutes les requêtes arrivent avec l'IP du load balancer et la règle bloque tout ou rien.

Traefik

# Middleware
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: ip-allowlist
spec:
  ipAllowList:
    sourceRange:
      - 192.168.1.0/24
      - 10.0.0.0/8

ingress-nginx (legacy)

metadata:
  annotations:
    nginx.ingress.kubernetes.io/whitelist-source-range: "192.168.1.0/24,10.0.0.0/8"

Taille maximale du body et timeouts

Avec Traefik, ces réglages sont des EntryPoint options côté contrôleur, pas des annotations Ingress. Configurer dans les values Helm de Traefik :

ports:
  web:
    transport:
      respondingTimeouts:
        readTimeout: "60s"
        writeTimeout: "60s"
        idleTimeout: "180s"

Avec ingress-nginx, les anciennes annotations restent disponibles mais le projet n'est plus maintenu :

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "60"

Authentification basique

L'authentification basique protège une route par un couple identifiant/mot de passe stocké dans un Secret, sans toucher au code de l'application. Elle transite en clair si vous n'avez pas activé TLS sur la route : réservez-la aux interfaces d'administration déjà servies en HTTPS. Sous Traefik, elle passe par un Middleware référencé depuis l'Ingress, en trois temps.

1. Créez le Secret avec le couple user/password

   htpasswd -c auth admin
   # Entrez le mot de passe
   kubectl create secret generic basic-auth --from-file=auth

2. Créez un Middleware Traefik

   basic-auth-middleware.yaml

   apiVersion: traefik.io/v1alpha1
   kind: Middleware
   metadata:
     name: basic-auth
   spec:
     basicAuth:
       secret: basic-auth

   kubectl apply -f basic-auth-middleware.yaml

3. Référencez le Middleware dans l'Ingress

   auth-ingress.yaml

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: auth-ingress
     annotations:
       traefik.ingress.kubernetes.io/router.middlewares: default-basic-auth@kubernetescrd
   spec:
     ingressClassName: traefik
     rules:
     - host: admin.example.com
       http:
         paths:
         - path: /
           pathType: Prefix
           backend:
             service:
               name: admin-service
               port:
                 number: 80

Sur un cluster encore servi par ingress-nginx, le même résultat s'obtient par trois annotations, nginx.ingress.kubernetes.io/auth-type: basic, auth-secret et auth-realm. Le format du Secret est identique, c'est toujours le fichier auth produit par htpasswd : seule la façon de le référencer change d'un contrôleur à l'autre.

Réécriture d'URL

Quand l'URL exposée diffère de celle attendue par le backend (par exemple /api/users côté Ingress doit arriver en /users côté Service), il faut un Middleware côté Traefik. Le préfixe retiré n'est pas restitué au backend : une application qui génère des liens absolus renverra des URL sans le /api, et les redirections qu'elle émet casseront. C'est la raison pour laquelle la réécriture se paie souvent en configuration supplémentaire côté application.

rewrite-ingress.yaml

# Middleware de réécriture
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: api-strip
spec:
  stripPrefix:
    prefixes:
      - /api
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite-ingress
  annotations:
    traefik.ingress.kubernetes.io/router.middlewares: default-api-strip@kubernetescrd
spec:
  ingressClassName: traefik
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80

Effet : /api/users arrive en /users côté api-service.

Un dernier conseil avant d'écrire une réécriture : essayez de vous en passer. Elle complique le diagnostic, parce que le chemin observé dans les journaux du contrôleur n'est plus celui que reçoit l'application. Quand vous maîtrisez le backend, le configurer pour accepter les chemins tels qu'ils sont exposés coûte moins cher à long terme qu'un Middleware de plus.

Vous croiserez encore l'équivalent ingress-nginx dans du code existant et dans beaucoup de tutoriels : l'annotation historique nginx.ingress.kubernetes.io/rewrite-target: /$2, avec un chemin /api(/|$)(.*) en pathType: ImplementationSpecific. Cette syntaxe à base d'expressions régulières n'est pas standard, et c'est précisément ce qui la rend difficile à porter vers un autre contrôleur, Traefik compris. Une raison de plus de ne pas en écrire de nouvelles.

Dépannage

Un Ingress qui ne fonctionne pas se diagnostique de l'extérieur vers l'intérieur : contrôleur joignable, règle reconnue, Service peuplé, Pods vivants. Le code HTTP renvoyé indique à quel étage la chaîne se rompt, ce qui évite de relire le YAML alors que le problème est un sélecteur de Service. Les commandes ci-dessous suivent cet ordre.

Vérifier l'état de l'Ingress

Le champ ADDRESS demande une lecture prudente, car il est vide dans deux situations opposées. Sur un cluster adossé à un LoadBalancer, un ADDRESS vide signale effectivement qu'aucun contrôleur n'a pris la ressource, donc un ingressClassName erroné ou un contrôleur absent. Sur kind, où il n'y a pas de LoadBalancer, il reste vide même quand tout fonctionne.

Ne concluez donc rien de ce champ seul : la preuve qui compte est une requête qui aboutit.

# Liste des Ingress
kubectl get ingress

# Détails d'un Ingress
kubectl describe ingress webapp-ingress

# Adresse assignée ?
kubectl get ingress webapp-ingress -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Vérifier l'Ingress Controller

Le contrôleur journalise chaque rechargement de sa configuration : si votre domaine n'apparaît jamais dans ses journaux, c'est qu'il n'a pas retenu la règle, et le problème se situe donc avant le routage.

# Identifier le namespace du Controller (traefik ici, kube-system sur k3s)
kubectl get pods -A | grep -iE 'traefik|ingress|haproxy|contour'

# Logs du Controller (adapter le namespace et le nom du deployment)
kubectl logs -n traefik deploy/traefik --tail=100

# Événements du namespace
kubectl get events -n traefik --sort-by=.lastTimestamp | tail -20

Erreurs courantes

Le code renvoyé situe la panne : un 404 vient du contrôleur qui n'a trouvé aucune règle, un 502 ou 503 vient du contrôleur qui a trouvé la règle mais pas de backend joignable derrière.

Erreur	Cause probable	Solution
404 Not Found	Pas de règle correspondante	Vérifiez host, path et Service
502 Bad Gateway	Service ou Pods inaccessibles	Vérifiez endpoints et pods
503 Service Unavailable	Aucun Pod disponible	Vérifiez kubectl get pods
Connection refused	Controller non exposé	Vérifiez le Service du Controller

Glissez pour voir

Debug pas à pas

Cette séquence remonte la chaîne maillon par maillon. L'étape des endpoints est celle qui révèle le plus d'erreurs : un Service sans endpoint signifie que son selector ne correspond à aucun label de Pod, et le YAML reste pourtant valide.

1. L'Ingress existe-t-il ?

   kubectl get ingress webapp-ingress

2. Le Service existe-t-il ?

   kubectl get svc webapp-service

3. Le Service a-t-il des endpoints ?

   kubectl get endpointslice -l kubernetes.io/service-name=webapp-service

4. Les Pods sont-ils Running ?

   kubectl get pods -l app=webapp

5. Le Controller voit-il l'Ingress ?

   # Adapter selon le contrôleur installé
   kubectl logs -n traefik deploy/traefik | grep webapp

Bonnes pratiques

Ces règles répondent aux deux faiblesses structurelles de l'API Ingress : son absence de valeurs par défaut explicites et sa dépendance aux annotations. Les appliquer dès la première ressource évite d'avoir à démêler le comportement d'un cluster où plusieurs contrôleurs cohabitent.

Configuration

Ces trois règles portent sur la prévisibilité : savoir quel contrôleur traite quelle ressource, et retrouver l'Ingress d'une application sans grep.

1. Toujours spécifier ingressClassName : évite les comportements imprévisibles
2. Un Ingress par application : plus facile à maintenir et débugger
3. Nommage cohérent, <app>-ingress pour identifier facilement

Sécurité

Un Ingress est le point d'entrée public du cluster : ce qui n'y est pas filtré arrive jusqu'aux Pods. Les noms d'annotations cités ci-dessous sont ceux de ingress-nginx ; sous Traefik, les équivalents sont le Middleware ipAllowList et les respondingTimeouts de l'EntryPoint, décrits plus haut.

1. Activez TLS : utilisez cert-manager pour automatiser les certificats
2. Restreignez les IPs, whitelist-source-range pour les routes sensibles
3. Limitez la taille des requêtes, proxy-body-size pour éviter les abus

Production

Le contrôleur concentre le trafic de toutes les applications exposées : sa panne les coupe toutes à la fois, d'où le besoin d'observabilité dédiée et d'un environnement de pré-production pour valider les annotations avant mise en ligne.

1. Surveillez les logs du Controller : configurez la collecte de logs
2. Monitorez les métriques : la plupart des Controllers exposent des métriques Prometheus
3. Testez en staging : les annotations peuvent avoir des effets inattendus

À retenir

Concept	Description
Ingress	Objet qui définit les règles de routage HTTP/HTTPS
Ingress Controller	Composant qui implémente réellement le routage
ingressClassName	Spécifie quel Controller gère l'Ingress
rules	Définit le routage par host et path
tls	Configure HTTPS avec un certificat
Annotations	Extensions spécifiques au Controller (non portables)

Glissez pour voir

Règle d'or : L'API Ingress est stable mais gelée. Pour les cas simples, elle reste parfaitement valide. Pour les besoins avancés ou les nouveaux projets, évaluez Gateway API.

FAQ : questions fréquentes sur l'Ingress

Ces questions reviennent souvent quand on expose des applications web dans Kubernetes. Les réponses ci-dessous reprennent les points clés du guide, rôle de l'Ingress Controller, choix entre Ingress et Gateway API, configuration TLS et diagnostic des erreurs 404.

Qu'est-ce qu'un Ingress dans Kubernetes ?

Un Ingress est une ressource Kubernetes qui expose des Services HTTP/HTTPS vers l'extérieur. Il centralise l'entrée du trafic web et le route par nom de domaine et par chemin d'URL, avec gestion du TLS.

Quelle est la différence entre un Ingress et un Service ?

Un Service expose des Pods au niveau TCP/UDP. Un Ingress travaille au niveau HTTP/HTTPS : routage par domaine et chemin, terminaison TLS. L'Ingress route le trafic web vers des Services ClusterIP internes.

Qu'est-ce qu'un Ingress Controller ?

L'Ingress Controller est le composant qui applique réellement les règles d'un Ingress. La ressource Ingress seule ne fait rien : il faut installer un contrôleur comme Traefik, Contour ou HAProxy Ingress.

Faut-il choisir Ingress ou Gateway API ?

L'API Ingress est stable mais gelée depuis 2022. Pour les cas simples, elle reste valable. Pour un nouveau projet ou des besoins avancés comme le traffic splitting, Kubernetes recommande Gateway API.

Comment configurer le HTTPS sur un Ingress ?

Ajoutez une section tls à l'Ingress référençant un Secret de type TLS. Pour automatiser l'obtention et le renouvellement des certificats Let's Encrypt, installez cert-manager et déclarez un ClusterIssuer.

Pourquoi mon Ingress renvoie-t-il une erreur 404 ?

Une 404 vient souvent d'une règle host ou path qui ne correspond pas, d'un ingressClassName absent ou faux, ou d'un Service cible sans endpoint. Vérifiez avec kubectl describe ingress et les logs du contrôleur.

Le contrôleur ingress-nginx est-il toujours utilisable ?

Non. Le projet a été archivé le 24 mars 2026 : dépôt en lecture seule, plus aucun correctif de sécurité. Sa dernière faille, CVE-2026-4342 (CVSS 8.8), permet une exécution de code et la fuite des Secrets du cluster. Corrigée en 1.13.9, 1.14.5 et 1.15.1, puis plus rien.

À quoi sert le champ ingressClassName ?

ingressClassName indique quel Ingress Controller doit prendre en charge la ressource Ingress. Sans lui, ou avec une valeur erronée, aucun contrôleur ne traite l'Ingress et le trafic n'est pas routé.

Contrôle de connaissances

Sept questions sur les points qui bloquent : le rôle du contrôleur, le champ ingressClassName, et ce que le routage par domaine exige côté client.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

7 questions

5 min.

80% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Pour aller plus loin

• Network Policies : Le filtrage du trafic vers les Pods exposés par l'Ingress Controller.
• Troubleshooting cluster : La méthode pour remonter la chaîne quand une règle Ingress reste sans effet.

×

📖 Voir la documentation →