Aller au contenu

URLs, routes et noms d'hôte

Comment un domaine, une URL et ses routes se combinent pour donner le nom d'hôte de chaque environnement, et comment le trafic atteint vos services.

ConceptDéveloppeur
Voir en Markdown

L'exposition d'une application repose sur trois objets déclarés dans l'architecture — le domaine, l'URL et la route — et sur un réglage de l'environnement, le préfixe. Leur combinaison donne un nom d'hôte différent dans chaque environnement, sans que vous ayez à déclarer l'URL plusieurs fois.

Définition

ObjetCe que c'estOù il se déclare
DomaineUn nom de domaine que l'app peut utiliser. Un domaine plateforme est fourni par Wakastart et partagé par toutes les apps. Un domaine personnalisé vous appartient et n'est visible que de votre app.Architecture > URLs > Domaines
URLUn sous-domaine posé sur un domaine, par exemple app sur exemple.fr. Une URL peut porter plusieurs routes.Architecture > URLs
RouteUne règle qui envoie un chemin (/, /api…) d'une URL vers un service de l'app.Carte de l'URL, Ajouter une route
Préfixe d'environnementUn segment inséré dans tous les noms d'hôte d'un environnement, par exemple staging.Onglet URLs & IAM de l'environnement
Domaine racineL'exposition d'un domaine personnalisé sans sous-domaine (exemple.fr).Architecture > URLs > Exposer sur le domaine racine

Une URL ou une route déclarée n'est encore qu'une intention. Elle ne produit ni DNS ni certificat tant qu'elle n'est pas instanciée dans un environnement. C'est le principe définition et instance appliqué au réseau.

Pourquoi ça existe

Une même application tourne en dev, en staging et en prod. Si chaque environnement avait ses propres URLs à déclarer, elles finiraient par diverger : une route ajoutée en staging et oubliée en prod. En déclarant les URLs une seule fois dans l'architecture, puis en les instanciant par environnement, vous garantissez que tous les environnements exposent la même chose, chacun sous son propre nom d'hôte.

Comment se compose le nom d'hôte

La plateforme calcule le nom d'hôte complet (FQDN) d'une URL dans un environnement avec cette règle :

Texte
<sous-domaine> . <préfixe de l'environnement, s'il existe> . <identifiant court de l'app, sur un domaine plateforme> . <domaine>
URL déclaréeEnvironnementPréfixeNom d'hôte obtenu
app sur exemple.fr (personnalisé)prodaucunapp.exemple.fr
app sur exemple.fr (personnalisé)stagingstagingapp.staging.exemple.fr
app sur un domaine plateforme <domaine-plateforme>, app monappdevdevapp.dev.monapp.<domaine-plateforme>
Domaine racine de exemple.frstagingstagingstaging.exemple.fr

L'identifiant court de l'app n'est ajouté que sur un domaine plateforme : c'est lui qui évite que deux apps se disputent le même nom. Sur votre propre domaine, vous êtes seul maître des noms.

La carte de chaque URL affiche le résultat dans Aperçu FQDN par environnement, avant toute mise en ligne.

Comment le trafic atteint vos services

Quand une route est en ligne, la requête suit ce chemin :

  1. Le DNS du nom d'hôte pointe vers la gateway de l'environnement.
  2. La gateway termine le TLS avec le certificat du nom d'hôte. Une requête en http:// reçoit une redirection permanente (301) vers https://.
  3. La gateway compare le chemin de la requête aux routes de l'URL et transmet la requête au service ciblé, sur le port déclaré dans la définition du service.

Le chemin est transmis tel quel : une requête vers https://app.exemple.fr/api/commandes arrive au service api avec le chemin /api/commandes. Votre service doit donc répondre sous le préfixe de sa route.

Trois types de correspondance sont proposés :

Type de cheminCorrespond àExemple pour /api
PathPrefix (par défaut)le chemin et tout ce qui commence par lui, segment par segment/api, /api/commandes ; pas /apis
Exactce chemin seulement/api
RegularExpressionles chemins qui satisfont l'expression/api/v[0-9]+/.*

Quand plusieurs routes d'une même URL correspondent, la plus précise l'emporte : une correspondance exacte passe avant un préfixe, et un préfixe long avant un préfixe court. La route / sert donc de route par défaut.

L'URL front officielle

Une seule route de l'app peut être marquée URL front officielle de l'app. Elle doit cibler un service de rôle FRONT. Ce repère désigne l'adresse d'entrée de votre front ; le choisir ne change ni le DNS ni le routage.

Exemples

  • Une app front + API sur un seul nom : URL app sur exemple.fr, route / vers le front, route /api vers l'API. En staging, tout est servi sous app.staging.exemple.fr.
  • Une API publique séparée : URL api sur exemple.fr, route / vers l'API. Le front appelle https://api.exemple.fr, ou mieux, lit l'URL dans sa variable ROUTE_API_URL (voir Variables et secrets).
  • Un environnement de démonstration sans domaine à vous : URL app sur un domaine plateforme, préfixe demo.

Pour aller plus loin