Traefik et le fournisseur fichier : publier un service hors conteneur

Pour publier un service qui ne tourne pas dans un conteneur, par exemple un service géré par systemd sur l'hôte, on décrit sa route dans un fichier que Traefik surveille avec le fournisseur fichier. Un tel service ne porte aucun label : le fournisseur Docker ne peut pas le découvrir. Cette leçon explique comment fonctionne ce fournisseur, ce qu'il recharge sans redémarrage et pourquoi une route correcte peut quand même donner une erreur si le backend est injoignable. Elle vise Traefik 3.7.15.

Ce que vous allez apprendre

La leçon suit le trajet d'une route : sa description dans un fichier, son rechargement, puis la vérification que le backend répond depuis Traefik.

• Expliquer pourquoi un service hors conteneur ne se découvre pas seul.
• Décrire un router et un service dans un fichier dynamique.
• Distinguer la configuration statique de la configuration dynamique.
• Prouver qu'un changement de route est pris en compte sans redémarrer Traefik.
• Vérifier la joignabilité du backend depuis la position réseau de Traefik.

Prérequis

Cette leçon prolonge la découverte Docker : elle suppose que vous connaissez les notions de router, de service et de backend, et que Traefik tourne déjà.

• Les notions de Traefik : entrypoints, routers, services et providers.
• La publication de conteneurs de Traefik avec Docker, pour mesurer la différence entre découverte et déclaration.
• Un service web simple géré par systemd, qui écoute sur un port local.

Pourquoi un service hors conteneur ne se découvre-t-il pas ?

Un fournisseur (provider) est la source qui dit à Traefik quoi publier. Le fournisseur Docker lit les métadonnées des conteneurs. Un service lancé par systemd n'a ni conteneur ni label : aucune source ne décrit sa route, donc Traefik l'ignore. Il faut lui fournir cette description à la main, et c'est le rôle du fournisseur fichier.

La description contient les mêmes objets que dans les labels, mais écrits dans un fichier YAML ou TOML : un router qui choisit la requête, et un service qui désigne le backend par son URL. La seule différence est la source, pas le modèle. Un objet défini ici porte le suffixe @file, comme un objet venu de Docker porte @docker.

Que recharge Traefik sans redémarrer ?

Traefik distingue deux niveaux de configuration. La configuration statique (entrypoints, fournisseurs activés, résolveurs ACME) est lue au démarrage : la changer impose de redémarrer Traefik. La configuration dynamique (routers, services, middlewares) peut changer pendant l'exécution.

Le fournisseur fichier appartient à la première catégorie par son activation, et à la seconde par son contenu. On l'active une fois dans la configuration statique avec providers.file.directory, qui désigne un répertoire. Les fichiers déposés dans ce répertoire sont ensuite surveillés : l'option providers.file.watch vaut true par défaut, d'après la référence du fournisseur. Ajouter, modifier ou supprimer une route ne demande alors aucun redémarrage.

Deux détails de la référence évitent des surprises. Les options filename et directory s'excluent l'une l'autre, et la documentation recommande directory. Après un rechargement, Traefik attend au moins 2s avant de prendre en compte un nouvel événement (providersThrottleDuration) : un changement n'est donc pas visible à la milliseconde près, et plusieurs modifications rapprochées sont regroupées.

Comment décrire une route vers un service hôte ?

Un fichier dynamique déclare trois choses : une règle qui reconnaît la requête, un point d'entrée où elle arrive, et l'adresse du backend. Le squelette ci-dessous montre leur place ; les valeurs entre chevrons sont à remplacer par celles de votre environnement.

http:
  routers:
    <nom-du-router>:
      entryPoints:
        - <entrypoint>
      rule: Host(`<nom-public>`)
      service: <nom-du-service>
  services:
    <nom-du-service>:
      loadBalancer:
        servers:
          - url: "http://<adresse-du-backend>:<port>"

Le squelette s'enchaîne ainsi : le router lit la requête, la règle Host compare le nom demandé, et le service transmet la requête à l'URL indiquée. Le nom <nom-du-service> relie les deux objets ; une faute de frappe à cet endroit désactive la route. Sur un backend qui ne parle pas HTTPS, l'URL commence par http://, et c'est Traefik qui garde la terminaison TLS côté client.

Pourquoi un backend « qui tourne » peut-il rester injoignable ?

L'adresse écrite dans url est résolue depuis Traefik, pas depuis votre terminal. C'est la cause la plus fréquente d'un 502 sur un service hôte. Deux cas reviennent.

• Traefik tourne dans un conteneur. Dans ce conteneur, 127.0.0.1 désigne le conteneur lui-même, pas l'hôte. Une URL http://127.0.0.1:<port> y échoue alors même que curl sur l'hôte réussit. Il faut une adresse que le conteneur sait joindre pour atteindre l'hôte.
• Le service n'écoute que sur la boucle locale. Un service lié à 127.0.0.1 n'accepte que les connexions venues de la machine elle-même. Depuis un conteneur ou un autre hôte, la connexion est refusée.

Pour trancher, comparez ce que le service annonce et ce que Traefik peut atteindre. systemctl status <unité> dit si l'unité est active, et ss -ltn liste les ports en écoute avec leur adresse. Un 502 immédiat indique une connexion refusée ; un 504 après un long silence indique plutôt un chemin réseau qui ne mène nulle part, comme le détaille Publier un service web.

Montez le répertoire, pas le fichier

Si Traefik tourne dans un conteneur, la référence déconseille de monter un fichier isolé : renommer le fichier sur l'hôte casse le lien, et le conteneur ne reçoit plus aucune notification. Montez le répertoire parent et désignez-le avec directory. Si le problème persiste, vérifiez la compatibilité du système de fichiers avec fsnotify, la bibliothèque qui capte les événements.

Comment prouver que la route a été prise en compte sans redémarrage ?

Une preuve se mesure avec deux observations qui doivent s'accorder : la route change de comportement, et Traefik n'a pas redémarré. Une seule ne suffit pas, car une route peut aussi changer parce que Traefik a été relancé.

1. Mesurez le comportement avant la modification : la réponse et le code HTTP pour le nom public concerné.
2. Notez ce qui identifie l'instance : l'heure de démarrage du processus ou du conteneur, ou son identifiant de processus.
3. Modifiez le fichier dynamique, puis attendez quelques secondes (le délai de 2s ci-dessus compte).
4. Refaites la requête et comparez la réponse, puis relisez l'identifiant ou l'heure de démarrage : ils doivent être inchangés.

Si la route ne change pas, ne supposez pas un échec du rechargement. Lisez les journaux de Traefik : une erreur de syntaxe dans un fichier y est enregistrée, et depuis la version 3.7.12 le nom du fichier figure dans le message. Contrôlez toujours le résultat par une requête réelle plutôt que par la seule absence d'erreur.

Mettre en pratique : publier un service systemd

L'exercice vous demande de rendre accessible un service hôte par un nom public, puis de montrer que Traefik a rechargé la configuration sans redémarrer. Les valeurs propres à l'environnement et les critères de réussite sont dans le scénario du lab.

Lab guidé Pratique

Apprendre à faire

Publier un service systemd avec le fournisseur fichier de Traefik

$ dsoxlab run pub-traefik-fichier

Environnement : VM·Durée : ~30 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-fichier 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-fichier
dsoxlab check pub-traefik-fichier

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 service hôte se publie avec la même mécanique de routage qu'un conteneur, à condition de lui fournir une description.

• Un service hors conteneur n'a pas de label : décrivez sa route dans un fichier surveillé.
• La configuration statique active le fournisseur ; la configuration dynamique se recharge sans redémarrage.
• Désignez un répertoire avec directory, et montez le répertoire parent si Traefik est dans un conteneur.
• L'URL du backend se résout depuis Traefik : 127.0.0.1 y désigne Traefik lui-même.
• Prouvez un rechargement à chaud par deux observations : la route a changé, l'instance n'a pas redémarré.

Contrôle de connaissances

Le quiz vérifie la différence entre configuration statique et dynamique, le rôle du fournisseur fichier et la joignabilité du backend.

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 →