Dépanner un point d'entrée Traefik : 404, 502, 504, certificat et redirections

Pour dépanner un point d'entrée Traefik, suivez le trajet de la requête : le certificat arrive avant HTTP, le 404 se produit au choix de la route, le 502 et le 504 au moment de joindre le backend, et une boucle de redirection se voit dans les en-têtes de réponse. Chaque symptôme désigne une couche, et chaque couche a son signal. Cette leçon donne l'ordre de lecture, les journaux à activer et les pièges qui font corriger la mauvaise couche. Elle vise Traefik 3.7.15.

Ce que vous allez apprendre

La leçon est organisée comme une démarche : situer le symptôme, lire le bon signal, puis valider la réparation par une réponse réelle.

• Placer un symptôme sur la couche qui le produit.
• Lire un journal d'accès : router, service cible, code et durée.
• Distinguer un certificat par défaut, un certificat de test et un certificat qui ne correspond pas au nom demandé.
• Expliquer une boucle de redirection et la mesurer avec curl.
• Valider une réparation par la réponse réelle, pas par l'absence d'erreur.

Prérequis

Cette leçon suppose que vous savez déjà publier un service et lire un code HTTP. Les mesures de base sont dans les leçons indiquées.

• Le trajet d'une requête, le SNI et les codes 404, 502 et 504 : Publier un service web.
• Le modèle de Traefik, ses providers et le tableau des erreurs courantes : Traefik.
• La publication de conteneurs et de services hôtes : Traefik avec Docker et le fournisseur fichier.
• Les journaux d'accès JSON : Observer Traefik.

Par quelle couche commencer ?

Commencez par la couche la plus proche du client, puis descendez. Une requête traverse le DNS, la connexion TCP, la négociation TLS, le choix de la route, la connexion au backend, puis la réponse. Un problème en amont masque tout ce qui suit : tant que le certificat est refusé, aucune requête HTTP n'atteint la route.

Symptôme observé	Couche concernée	Première observation
Avertissement de certificat	TLS, avant HTTP	sujet et émetteur du certificat présenté
404 page not found	choix de la route	ligne du journal d'accès, router associé
502	connexion au backend	URL cible du service dans le journal d'accès
504 ou réponse très lente	attente du backend	durée de la ligne, délais configurés
Redirections qui ne finissent pas	redirection	chaîne d'en-têtes Location

Glissez pour voir

Une règle simple évite de modifier au hasard : ne changez qu'une chose à la fois, puis refaites la même requête. Si deux pannes coexistent, la première réparation révèle la suivante, et c'est normal.

Quels journaux faut-il activer avant de diagnostiquer ?

Par défaut, Traefik journalise au niveau ERROR, et le journal d'accès est désactivé. Un 404 sans route, un 502 ou un 504 ne laissent alors aucune trace dans les journaux du processus : un journal vide ne prouve pas que Traefik n'a rien vu. Activez le journal d'accès avant de reproduire la panne, comme le détaille Observer Traefik.

Le format JSON donne des champs nommés. Quatre suffisent pour la plupart des diagnostics :

• RouterName, le router retenu pour la requête ;
• ServiceURL, le backend réellement contacté ;
• DownstreamStatus, le code renvoyé au client ;
• Duration, le temps passé, en nanosecondes.

Lisez-les ensemble. Un code 404 sans router retenu parle de route. Un code 502 avec une ServiceURL inattendue parle d'adresse ou de port. Une Duration proche de 30 secondes avec un 504 parle d'un backend qui ne répond pas à la connexion. Pour les erreurs de construction d'objets (règle mal écrite, middleware inexistant), le niveau ERROR suffit : le message nomme l'objet fautif.

Que signifie un 404 ?

Un 404 de Traefik signifie qu'aucun router actif ne correspond à la requête. La route peut manquer, être écrite autrement que le nom demandé, ou avoir été désactivée par une erreur de configuration. Les causes se vérifient dans l'ordre suivant.

1. Le nom et le point d'entrée de la requête correspondent-ils à la règle et aux entryPoints du router ?
2. Le router est-il actif ? Un router qui cite un service ou un middleware inexistant est désactivé, et l'erreur est écrite au niveau ERROR.
3. L'objet cité est-il écrit avec le bon suffixe de fournisseur (@file, @docker) ? Un oubli fait chercher l'objet dans le mauvais fournisseur.
4. Si les routes viennent d'un fichier, le fichier a-t-il été rechargé ? Depuis la version 3.7.12, une erreur de lecture mentionne le nom du fichier.

Si l'API de Traefik est activée, elle liste chaque router avec son statut et son éventuelle erreur ; l'exposer sans protection est un risque, traité dans Sécuriser Traefik.

Que révèlent un 502 et un 504 ?

Les deux codes parlent du backend, mais pas de la même défaillance. Un 502 indique que la connexion a été refusée ou que la réponse est invalide. Un 504 indique que le backend n'a pas répondu dans le délai.

Les délais par défaut expliquent des comportements qui surprennent. Dans la référence du transport de serveur, forwardingTimeouts.dialTimeout vaut 30s : Traefik abandonne alors la connexion et renvoie un 504. En revanche forwardingTimeouts.responseHeaderTimeout vaut 0s, c'est-à-dire aucun délai : un backend qui accepte la connexion puis répond très lentement ne provoque pas de 504 tant qu'on n'a pas fixé ce délai. Une page « lente » n'est donc pas forcément une panne de Traefik.

Pour trancher entre la route, le réseau et l'application, comparez ces trois observations : l'URL cible du journal d'accès, la réponse du backend appelé de la machine où tourne Traefik, et la durée de la ligne. Si le backend répond bien de là mais pas par Traefik, cherchez un décalage de port, de réseau ou de protocole (HTTP contre HTTPS) dans la définition du service.

Pourquoi le navigateur affiche-t-il un avertissement de certificat ?

L'avertissement vient de la négociation TLS, avant toute requête HTTP. Traefik choisit le certificat d'après le nom que le client annonce (le SNI) : inspectez ce qui est réellement présenté pour ce nom.

openssl s_client -connect <hote>:443 -servername <nom-demande> </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

La commande affiche le sujet, l'émetteur et les dates du certificat servi pour ce nom. Trois lectures sont possibles.

• Le sujet est TRAEFIK DEFAULT CERT : aucun certificat ne correspond au nom annoncé, donc Traefik sert son certificat par défaut, auto-signé. Cherchez un router sans TLS, un nom différent du nom demandé, ou un certificat absent.
• L'émetteur est une autorité de test ou de staging : le certificat est valide pour une autre chaîne de confiance, que le navigateur n'accepte pas. C'est normal en laboratoire, une erreur en production.
• Le sujet est le bon, mais les dates sont dépassées : le renouvellement a échoué. Les causes sont décrites dans HTTPS automatique avec Traefik.

Comment naît une boucle de redirection ?

Une boucle apparaît quand une redirection renvoie le client vers une adresse qui déclenche la même redirection. Le navigateur finit par afficher un message d'erreur sans page. Deux situations en sont la source classique.

• Une redirection de HTTP vers HTTPS est attachée à un router qui répond aussi en HTTPS : la requête déjà chiffrée est renvoyée vers elle-même.
• Un autre proxy placé devant Traefik termine le TLS et lui parle en HTTP : Traefik croit recevoir du clair et redirige vers HTTPS, le proxy renvoie du clair, et ainsi de suite.

La redirection se mesure sans navigateur. curl suit les redirections avec -L, et --max-redirs limite leur nombre.

curl -sIL --max-redirs 5 http://<nom-demande>/

Si la chaîne tourne en rond, curl s'arrête avec le message Maximum (5) redirects followed et vous voyez la même adresse revenir dans les en-têtes Location. La correction consiste à placer la redirection là où la requête est encore en clair, ou à indiquer à Traefik le schéma réel quand un proxy se trouve devant. Le détail de la redirection par entrypoint est dans HTTPS automatique avec Traefik.

Réparez, puis prouvez

Une réparation n'est terminée que si la réponse réelle a changé : refaites la requête du symptôme initial et comparez code, certificat et durée. Vérifiez aussi que Traefik n'a pas été redémarré si la panne venait d'un fichier dynamique : un rechargement à chaud se constate, il ne se suppose pas.

Mettre en pratique : remettre un point d'entrée en état

L'exercice présente plusieurs services devenus instables, avec des pages absentes, des erreurs de passerelle, des lenteurs, un avertissement de certificat et une redirection sans fin. Vous devez localiser chaque panne dans les journaux et les réponses, réparer la configuration, puis vérifier le résultat.

Lab guidé Pratique

Apprendre à faire

Dépanner le routage et TLS dans Traefik

$ dsoxlab run pub-traefik-depannage

Environnement : VM·Durée : ~45 min

Vérification : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que DSOXLab et comment l'installer

DSOXLab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Il faut Python 3.11 ou plus récent, uv ou pipx, et git. Le guide d'installation détaille ces prérequis ; sous Windows, ou sur un Mac sans Python, passez plutôt par l'appliance.

Ce lab démarre des machines virtuelles : il demande en plus ansible-playbook, un hyperviseur (KVM ou Incus), Terraform et la virtualisation matérielle (/dev/kvm), c'est-à-dire, dans une VM VirtualBox, la virtualisation imbriquée. La première fois, dsoxlab start pub-traefik-depannage vérifie tout cela avant de créer les machines. Préparer le poste pour les labs vm.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/publier-service-dsoxlab-training

Avant de lancer le lab, vérifiez :

• DSOXLab installé
• catalogue disponible
• environnement compatible (shell isolé ou VM)

Pour le vérifier, rien n'est sondé depuis cette page : lancez dsoxlab doctor. Lire le diagnostic

Lancer ce lab, puis valider votre travail :

dsoxlab run pub-traefik-depannage
dsoxlab check pub-traefik-depannage

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille le calcul du score et les pièges.

À retenir

Un diagnostic fiable suit l'ordre de la requête et s'appuie sur un signal par couche.

• Le certificat arrive avant HTTP ; le 404 se produit au choix de la route ; le 502 et le 504 au moment de joindre le backend.
• Activez le journal d'accès avant de reproduire la panne : le niveau par défaut ne garde pas ces codes.
• TRAEFIK DEFAULT CERT signale un nom sans certificat, pas un certificat expiré.
• Sans délai de réponse configuré, un backend lent ne produit pas de 504.
• Une boucle de redirection se mesure avec curl -L --max-redirs.
• Ne changez qu'une chose à la fois, puis refaites la même requête.

Contrôle de connaissances

Le quiz vérifie l'ordre de lecture des couches, les codes d'erreur et les signaux propres à chaque panne.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

8 questions

8 min.

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

×

📖 Voir la documentation →