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 projet communautaire ingress-nginx — historiquement le contrôleur de référence de ce guide — a été retiré le 24 mars 2026. Le dépôt GitHub est en lecture seule, plus aucun release, plus aucun patch CVE. La cause : charge de maintenance insoutenable + accumulation de vulnérabilités liées aux annotations snippets.

L'API Ingress (la ressource Kubernetes elle-même) reste stable et supportée. C'est uniquement le contrôleur communautaire qui s'arrête.

Conséquences pratiques :

• Les exemples Helm ingress-nginx/ingress-nginx qu'on trouve encore en ligne continuent de fonctionner mais ne reçoivent plus de correctifs sécurité — ce guide a basculé sur Traefik comme contrôleur de référence.
• Pour un nouveau cluster : préférer Gateway API (API Kubernetes moderne, recommandée), ou un contrôleur Ingress activement maintenu (Traefik, Contour, HAProxy Ingress, ou le produit commercial NGINX Ingress Controller de NGINX Inc. — différent du projet communautaire ingress-nginx).
• Pour un cluster existant : planifier une migration vers Gateway API ou un autre contrôleur dans les prochains mois.

Source : SIG Network — Ingress NGINX retired (24 mars 2026).

API Ingress gelée — Gateway API en succession

L'API Ingress reste stable et supportée, mais elle est gelée depuis 2022 : pas de nouvelles fonctionnalités. Pour les nouveaux projets ou les besoins avancés (routage gRPC, traffic splitting, header matching, mTLS), Kubernetes recommande Gateway API.

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 ?

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.

Comment fonctionne un Ingress ?

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 (Minikube, Kind, K3s, ou cloud)
• 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

Plusieurs Ingress Controllers existent, chacun avec ses spécificités :

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, livré par défaut sur k3d/k3s, et il supporte aussi Gateway API (chemin de migration cohérent).

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 k3d / k3s : déjà installé

Si vous suivez ce guide sur un cluster k3d ou k3s, Traefik est déjà déployé par défaut dans le namespace kube-system. Vous pouvez sauter l'installation Helm et passer directement à la création de l'Ingress.

kubectl get ingressclass
# NAME                CONTROLLER                      PARAMETERS   AGE
# traefik (default)   traefik.io/ingress-controller   <none>       2m

Créer votre premier Ingress

Préparer l'application et le Service

Déployez une application simple :

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
        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

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

Depuis Kubernetes 1.18+, spécifiez toujours ingressClassName pour indiquer quel Controller doit gérer cet Ingress. Sans cette valeur, le comportement dépend de la configuration du cluster.

kubectl apply -f webapp-ingress.yaml

Tester l'accès

Récupérez l'adresse du Controller :

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'IP dépend de votre environnement

En local, l'adresse à utiliser dépend de comment votre Controller est exposé : 127.0.0.1 avec k3d ou Kind+port mapping, IP Minikube, IP de VM, etc. 127.0.0.1 ne fonctionne que si le Controller écoute réellement sur localhost.

Testez :

curl -H "Host: webapp.local" http://127.0.0.1
# ou, après avoir mis à jour /etc/hosts :
curl http://webapp.local

Routage multi-domaines

Un Ingress peut router plusieurs domaines vers différents Services :

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

Vous pouvez aussi router différents chemins vers différents Services :

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

pathType : Prefix vs Exact

• Prefix : /api matche /api, /api/, /api/users
• Exact : /api matche uniquement /api

L'ordre des paths n'a pas d'importance ; Kubernetes choisit le path le plus spécifique.

Configurer TLS avec cert-manager

Installer cert-manager

Consultez la documentation officielle cert-manager pour la version actuelle. Installation typique :

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

Vérifiez l'installation :

kubectl get pods -n cert-manager

Créer un ClusterIssuer pour Let's Encrypt

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

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 ne réussira que si :

• Le domaine résout vers l'IP de votre Ingress Controller
• L'Ingress est accessible depuis Internet (pour HTTP01)
• Le challenge ACME fonctionne réellement

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)

Annotations = spécifiques au Controller, non portables

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/*). C'est précisément ce que Gateway API corrige en standardisant ces comportements dans l'API.

Les exemples ci-dessous montrent le même besoin sur Traefik (recommandé) et ingress-nginx (cluster legacy).

Redirection HTTPS

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

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

Pour protéger une route avec un login/mot de passe sous Traefik :

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

Équivalent ingress-nginx

Sur un cluster ingress-nginx (legacy, non maintenu), les annotations équivalentes sont nginx.ingress.kubernetes.io/auth-type: basic, auth-secret, auth-realm. Le format du Secret est identique (fichier auth produit par htpasswd).

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 :

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.

Préférer la config backend

La réécriture d'URL complexifie le debug. Préférez configurer vos backends pour accepter les paths tels qu'exposés quand c'est possible.

Équivalent ingress-nginx (legacy)

Sur un cluster ingress-nginx, l'annotation historique est nginx.ingress.kubernetes.io/rewrite-target: /$2 avec un path /api(/|$)(.*) en pathType: ImplementationSpecific — syntaxe regex non standard, plus difficile à porter.

Dépannage

Vérifier l'état de l'Ingress

# 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

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

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

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

Erreurs courantes

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

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 endpoints 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 kube-system deploy/traefik | grep webapp

Bonnes pratiques

Configuration

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é

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

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

Contrôle de connaissances

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

7 questions

5 min.

90% 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

À 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.

Prochaines étapes

Gateway API L'alternative moderne recommandée par Kubernetes

Services Kubernetes Comprendre les Services avant d'exposer avec Ingress

Network Policies Sécurisez le trafic réseau dans votre cluster

Debug applications Diagnostiquez les problèmes de connectivité

×

📖 Voir la documentation →