Traefik sur Kubernetes : Gateway API, CRD et IngressRoute

Traefik est un ingress controller Kubernetes qui expose vos Services en HTTP/HTTPS avec une découverte automatique de la configuration. Vous décrivez le routage dans des objets Kubernetes, Traefik les applique en temps réel, sans redémarrage. Ce guide s'adresse aux administrateurs qui déploient Traefik sur un cluster et hésitent entre Gateway API, CRD IngressRoute et Ingress standard.

Vous installerez Traefik avec Helm, puis exposerez une application avec chacun des trois modèles, avant de voir la sécurité TLS, la haute disponibilité et la migration depuis NGINX.

Ce que vous allez apprendre

• Installer Traefik sur Kubernetes avec Helm et vérifier son déploiement.
• Choisir entre Gateway API, IngressRoute et Ingress standard.
• Exposer une application avec les CRD Traefik et attacher un middleware.
• Router avec la Gateway API (le standard CNCF).
• Sécuriser automatiquement en HTTPS via cert-manager.
• Migrer depuis Ingress NGINX et diagnostiquer les erreurs courantes.

Prérequis

• Un cluster Kubernetes fonctionnel et kubectl configuré (un cluster k3d de test convient ; désactivez alors le Traefik intégré de k3s avec --disable=traefik).
• Helm 3+ installé.
• Des notions de Service, Deployment et Ingress Kubernetes.

Trois façons d'exposer une application

Traefik comprend trois modèles de routage sur Kubernetes. Le bon choix dépend de vos besoins de portabilité et de fonctionnalités avancées.

Modèle	Quand l'utiliser	Portabilité
Gateway API	Nouveaux projets, standard CNCF, gouvernance multi-équipes	Portable entre ingress controllers
IngressRoute (CRD Traefik)	Fonctionnalités avancées Traefik (middlewares, TCP/UDP, mirroring)	Spécifique à Traefik
Ingress standard	Compatibilité maximale, cas simples	Portable mais limité

Glissez pour voir

Gateway API est l'avenir de l'ingress Kubernetes, détaillé dans le guide Gateway API. Les CRD IngressRoute exposent tout le potentiel de Traefik. L'Ingress standard reste pratique pour un service simple ou pour rester portable.

Installer Traefik avec Helm

Le chart Helm officiel installe le contrôleur, ses CRD et le service LoadBalancer. C'est la méthode recommandée en production.

1. Ajouter le dépôt Helm et le rafraîchir :

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

2. Installer Traefik dans son namespace, en épinglant la version de l'image :

   helm install traefik traefik/traefik \
     --namespace traefik --create-namespace \
     --set image.tag=v3.7.6 \
     --wait

3. Vérifier le déploiement et la version réellement déployée :

   kubectl -n traefik get deploy traefik \
     -o jsonpath='{.spec.template.spec.containers[0].image}'
   # docker.io/traefik:v3.7.6

   Les CRD Traefik (ingressroutes.traefik.io, middlewares.traefik.io...) sont installées automatiquement par le chart.

Personnaliser via un fichier values

Pour la production, préférez un fichier values.yaml versionné plutôt que des --set répétés. Vous y déclarez les entrypoints, les ressources, le nombre de réplicas et les providers activés. Appliquez-le avec helm install traefik traefik/traefik -f values.yaml.

Router avec IngressRoute (CRD Traefik)

L'IngressRoute est l'objet natif de Traefik. Il expose les matchers complets de Traefik (Host, PathPrefix, Headers...) et se combine avec les middlewares.

Déployez une application de test puis exposez-la :

whoami-ingressroute.yaml

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: whoami
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`whoami.example.com`)
      kind: Rule
      services:
        - name: whoami
          port: 80

Appliquez et vérifiez que la route est prise en compte :

kubectl apply -f whoami-ingressroute.yaml
kubectl get ingressroute whoami

Une requête avec l'en-tête Host: whoami.example.com sur l'entrypoint web atteint alors le Service whoami. Le routage est immédiat, sans rechargement du contrôleur.

Attacher un middleware

Les middlewares transforment la requête avant qu'elle n'atteigne le service (ajout de headers, authentification, rate limiting). Déclarez-en un et référencez-le dans la route :

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: secure-headers
spec:
  headers:
    frameDeny: true
    contentTypeNosniff: true
    stsSeconds: 31536000
---
# dans l'IngressRoute, sur la route concernée :
#   middlewares:
#     - name: secure-headers

Le catalogue complet est traité dans le guide Middlewares Traefik.

Traefik v3.7 durcit certains middlewares

Depuis Traefik v3.7, un middleware BasicAuth sans utilisateurs est rejeté et sa route démontée, et StripPrefix renvoie une erreur 400 si le chemin résultant contient . ou ... Vérifiez vos middlewares après une montée de version.

Router avec la Gateway API

La Gateway API est le standard Kubernetes portable entre contrôleurs. Traefik l'implémente comme provider. Installez d'abord les CRD Gateway API (canal standard), puis activez le provider dans les values Helm.

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/standard-install.yaml

Version des CRD Gateway API

Traefik v3.7 s'aligne sur les CRD Gateway API v1.5.1 ou plus récentes, et TLSRoute est passé au canal standard (plus besoin du canal expérimental). Installez une version récente des CRD avant d'activer le provider.

Une fois le provider kubernetesGateway activé, vous déclarez une Gateway (les points d'entrée) et des HTTPRoute (le routage), exactement comme décrit dans le guide Gateway API. L'intérêt : le même manifeste fonctionne avec un autre ingress controller compatible.

Ingress standard Kubernetes

Traefik consomme aussi les Ingress standard. C'est le choix de la portabilité pour des besoins simples. Indiquez la classe d'ingress traefik :

whoami-ingress.yaml

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

Fonctionnalités limitées

L'Ingress standard ne couvre pas tout le potentiel de Traefik : routage TCP/UDP, mirroring, middlewares avancés. Pour ces cas, préférez les CRD IngressRoute ou la Gateway API.

Sécuriser en HTTPS avec cert-manager

Pour des certificats Let's Encrypt ou une CA interne gérés par Kubernetes, cert-manager est le compagnon naturel de Traefik. Il émet et renouvelle les certificats dans des Secrets kubernetes.io/tls, que Traefik consomme via un IngressRoute en TLS ou un TLSStore.

C'est l'alternative à l'ACME intégré de Traefik quand vous voulez centraliser la gestion des certificats du cluster, y compris pour des workloads non-Traefik. Pour l'ACME géré directement par Traefik, voir Traefik SSL/TLS et ACME.

Migration depuis Ingress NGINX

Traefik peut lire une partie des annotations Ingress NGINX, ce qui facilite une migration progressive. Activez le provider correspondant, puis migrez les Ingress un par un.

• Les annotations de routage de base (réécritures simples, TLS) sont majoritairement prises en charge.
• Les annotations spécifiques NGINX avancées (configuration snippet, comportements fins) ne le sont pas et doivent être retranscrites en middlewares Traefik ou en Gateway API.
• La stratégie recommandée : faire cohabiter les deux contrôleurs le temps de la bascule, migrer service par service, puis retirer NGINX une fois les routes validées.

Provider ingress-nginx et RBAC

Le provider ingress-nginx de Traefik v3.7 exige le droit configmaps dans le RBAC pour lire certaines annotations (comme custom-headers). Ajustez le ClusterRole de Traefik si vous l'activez.

Multi-tenancy et haute disponibilité

Sur un cluster partagé, cloisonnez Traefik et rendez-le résilient.

• Restreindre les namespaces : limitez le provider Kubernetes à certains namespaces pour qu'une équipe ne route pas vers les services d'une autre.
• RBAC minimal : n'accordez au ServiceAccount de Traefik que les verbes nécessaires (lecture des Ingress, IngressRoute, Services, Secrets).
• Plusieurs réplicas : augmentez deployment.replicas dans les values pour tolérer la perte d'un pod, et répartissez-les avec des règles d'anti-affinity.

Depuis Traefik v3.7, l'option crossProviderNamespaces permet de restreindre les références cross-provider à des namespaces précis, un renfort utile en environnement multi-tenant.

Dépannage

Quand une route ne répond pas, remontez du contrôleur vers l'objet de routage.

Symptôme	Cause probable	Solution
IngressRoute ignoré	CRD absentes ou mauvais entryPoints	Vérifier kubectl get crd | grep traefik et le nom de l'entrypoint
404 sur toutes les routes	Traefik intégré de k3s encore actif	Recréer le cluster avec --disable=traefik
Certificats non générés	Issuer cert-manager non prêt ou challenge en échec	kubectl describe certificate puis challenge
Route Gateway API inactive	CRD Gateway API trop anciennes	Installer des CRD v1.5.1+

Glissez pour voir

Le dashboard Traefik (activé dans les values) affiche en direct les routeurs, services et middlewares détectés : c'est le premier réflexe pour voir si une route est bien prise en compte.

À retenir

• Traefik s'installe proprement sur Kubernetes avec le chart Helm officiel, qui pose aussi les CRD.
• Trois modèles coexistent : Gateway API (portable, standard), IngressRoute (avancé, natif Traefik), Ingress standard (simple, portable).
• Les middlewares enrichissent le routage, mais v3.7 durcit BasicAuth et StripPrefix.
• cert-manager gère les certificats du cluster ; l'ACME intégré reste une option pour Traefik seul.
• La Gateway API demande des CRD v1.5.1+ avec Traefik v3.7.
• Cloisonnez par namespace et RBAC, et déployez plusieurs réplicas pour la haute disponibilité.

Prochaines étapes

SSL/TLS avec Let's Encrypt ACME et certificats automatiques gérés par Traefik.

Middlewares Traefik Auth, rate limiting, headers de sécurité.

cert-manager Certificats TLS automatiques pour tout le cluster.

Gateway API Le standard de routage Kubernetes portable.

×

📖 Voir la documentation →