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 : API stable mais gelée

L’API Ingress reste stable et supportée, mais elle est gelée : pas de nouvelles fonctionnalités. Pour les nouveaux projets ou les besoins avancés (routage gRPC, traffic splitting, header matching), 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	Points forts
ingress-nginx	Le plus répandu, stable, beaucoup d’exemples
Traefik	Léger, config dynamique, bon pour microservices
HAProxy Ingress	Performant, adapté aux charges élevées
Contour	Basé sur Envoy, moderne

Glissez pour voir

Retirement du projet ingress-nginx

Le projet Kubernetes a annoncé la retraite d’ingress-nginx (le contrôleur communautaire). L’API Ingress elle-même reste supportée. Pour les nouveaux projets, évaluez Gateway API ou d’autres contrôleurs activement maintenus.

Installation avec Helm (ingress-nginx)

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

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

Vérifiez l’installation :

kubectl get pods -n ingress-nginx
kubectl get svc -n ingress-nginx

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

# Adresse du Service Ingress Controller
kubectl get svc -n ingress-nginx my-ingress-ingress-nginx-controller

# Sur Minikube
minikube ip

# Sur Kind avec port mapping
# Généralement 127.0.0.1 si configuré

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

# Remplacez par l'IP réelle de votre Controller
echo "192.168.49.2 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é : IP Minikube, 127.0.0.1 avec Kind et port mapping, IP de VM, etc. 127.0.0.1 ne fonctionne que si le Controller écoute réellement sur localhost.

Testez :

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

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: nginx
  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 ingress-nginx courantes

Annotations = spécifiques au Controller

Les annotations nginx.ingress.kubernetes.io/* sont spécifiques à ingress-nginx. Elles ne sont pas portables vers Traefik, HAProxy ou d’autres Controllers.

Redirection HTTPS

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

Restriction par IP

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

Taille maximale du body

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"

Timeouts

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "60"

Authentification basique

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

1. Créez le fichier htpasswd

   htpasswd -c auth myuser
   # Entrez le mot de passe

2. Créez le Secret

   kubectl create secret generic basic-auth --from-file=auth

3. Configurez l’Ingress

   auth-ingress.yaml

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: auth-ingress
     annotations:
       nginx.ingress.kubernetes.io/auth-type: "basic"
       nginx.ingress.kubernetes.io/auth-secret: "basic-auth"
       nginx.ingress.kubernetes.io/auth-realm: "Zone protégée"
   spec:
     ingressClassName: nginx
     rules:
     - host: admin.example.com
       http:
         paths:
         - path: /
           pathType: Prefix
           backend:
             service:
               name: admin-service
               port:
                 number: 80

Réécriture d’URL

Quand l’URL exposée diffère de celle attendue par le backend :

rewrite-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /api(/|$)(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: api-service
            port:
              number: 80

Exemple : /api/users est réécrit en /users avant d’être envoyé au backend.

Utilisez rewrite-target avec parcimonie

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.

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

# Pods du Controller
kubectl get pods -n ingress-nginx

# Logs du Controller
kubectl logs -n ingress-nginx deploy/my-ingress-ingress-nginx-controller --tail=100

# Événements
kubectl get events -n ingress-nginx --sort-by=.lastTimestamp

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 ?

   kubectl logs -n ingress-nginx deploy/my-ingress-ingress-nginx-controller | 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 →