Modes de routage — Sous-chemin ou sous-domaine

Choisissez si les applications Scrydon destinées au navigateur partagent un nom d'hôte ou utilisent un nom d'hôte par application.

Les applications Scrydon destinées au navigateur prennent en charge deux modes de routage au moment du déploiement. Les mêmes images d'application servent les deux modes ; routing.mode sélectionne les URL publiques, les chemins de base, les objets Gateway API, les cookies et la configuration CORS.

	Sous-chemin (`subpath`, par défaut)	Sous-domaine (`subdomain`)
Exemples d'URL	`app.example.com/cortex` `app.example.com/analytics`	`cortex.example.com` `analytics.example.com`
DNS	Un enregistrement A	Un wildcard ou un enregistrement A par application
TLS	Un certificat d'hôte	Un wildcard ou un certificat par application
Gateway	Une `gateway-frontdoor` avec un listener `http` et un listener `https`	La même `gateway-frontdoor` unique, avec un listener HTTPS par nom d'hôte d'application activée
Routes	Une `HTTPRoute` par application activée, portant ses préfixes `routing.paths.*`	Une `HTTPRoute` par application navigateur/realtime activée, correspondant à `/` sur son propre nom d'hôte
Cookies	Limités à l'hôte	Domaine enregistrable partagé
CORS	Une origine publique	Une origine publique par application
Idéal pour	Installations client et sur site	SaaS ou domaines indépendants par application

Utilisez le mode sous-chemin par défaut, sauf si vous avez besoin de politiques DNS, TLS ou SSO distinctes par application.

Fonctionnement des chemins de base

Le chart résout le préfixe de chaque application et injecte BASE_PATH. L'application monte ses routes et ses actifs sous ce préfixe, injecte la valeur dans le code client et configure TanStack Router avec le même chemin de base. Les services API suivent la même règle.

Une simple suppression du préfixe en périphérie ne suffit pas, car les pages rendues côté serveur et les actifs hachés ont besoin d'un chemin public connu de l'application. Aucun rebuild n'est nécessaire lors d'un changement de mode.

Démarrage rapide en sous-chemin

routing:
  mode: subpath
  host: app.example.com
  # paths:
  #   cortex: /cortex
  #   agentic: /agentic
  #   analytics: /analytics
  #   platform: /platform
  #   apiAuth: /api/auth
  #   apiOntology: /api/ontology
  #   apiTable: /api/table
  #   agenticRealtime: /agentic/realtime

Créez un enregistrement A pour app.example.com. Lorsque TLS est activé, le listener https référence tls-frontdoor et le chart génère une HTTPRoute par application activée portant les chemins de cette application. L'ordre des règles n'a aucune importance : la Gateway API impose la précédence du préfixe correspondant le plus long sur toutes les routes d'un listener, donc /agentic/realtime l'emporte toujours sur /agentic et la règle racine / est simplement la moins prioritaire.

La porte d'entrée route également /api/router et /api/mcp vers la plateforme dès que auth est activé — les points de terminaison AI Gateway et Scrydon MCP vers lesquels les développeurs pointent Claude Code, Codex et Cursor. Ce ne sont volontairement pas des clés routing.paths : contrairement à apiAuth, dont la valeur devient aussi le point de montage du serveur, ces deux chemins sont figés des deux côtés (la CLI les écrit dans ANTHROPIC_BASE_URL et dans l'entrée MCP de Claude) ; une valeur configurable ne pourrait donc router que vers un endroit qu'aucun des deux côtés n'emprunte. En mode sous-domaine, aucune règle dédiée n'est nécessaire : l'hôte auth transmet déjà tout son préfixe à la plateforme. Voir AI Gateway.

Démarrage rapide en sous-domaine

routing:
  mode: subdomain

auth:
  publicUrl: https://auth.example.com
  gateway: { hostname: auth.example.com }
  corsOrigins:
    - https://app.example.com
    - https://cortex.example.com
    - https://agentic.example.com
    - https://ws-agentic.example.com
    - https://analytics.example.com

platform:
  publicUrl: https://app.example.com
  gateway: { hostname: app.example.com }

cortex:
  publicUrl: https://cortex.example.com
  gateway: { hostname: cortex.example.com }

agentic:
  publicUrl: https://agentic.example.com
  publicSocketUrl: https://ws-agentic.example.com
  app:
    gateway: { hostname: agentic.example.com }
  realtime:
    gateway: { hostname: ws-agentic.example.com }

analytics:
  publicUrl: https://analytics.example.com
  gateway: { hostname: analytics.example.com }

Créez un enregistrement A par hôte, ou utilisez un wildcard. Chaque application activée obtient son propre listener HTTPS sur l'unique Gateway, référençant son Secret TLS correspondant (tls-auth, tls-platform, tls-cortex, tls-agentic, tls-agentic-realtime, tls-analytics), sauf si gateway.tls.existingSecret pointe tous les listeners vers un seul certificat. Les sessions inter-sous-domaines exigent que toutes les URL publiques partagent le même domaine enregistrable.

Les annotations de cookie sticky qui se trouvaient sous agentic.realtime ont disparu. L'affinité de session pour les backends Gateway API ne fait pas partie du canal standard : agentic-realtime n'a donc aucune affinité si vous l'exécutez avec plus d'un réplica en mode sous-domaine. Il est livré avec replicas: 1.

Notebooks Marimo

Marimo n'a pas de nom d'hôte, de chemin, d'HTTPRoute ou de secret TLS public. Le document du notebook, la requête Connect, la requête Run d'une cellule, le proxy HTTP et le proxy WebSocket restent tous sur l'origine Analytics authentifiée :

sous-chemin : https://app.example.com/analytics/notebooks/...
sous-domaine : https://analytics.example.com/notebooks/...

Le moteur de rendu de documents sans état et les runtimes isolés sont des services privés du cluster. Ne créez pas d'enregistrement DNS marimo.example.com et n'exposez pas directement les ports du runtime.

DNS et TLS

Pour les choix d'émetteur, les domaines privés et les certificats d'entreprise, consultez Certificats TLS.

Le sous-chemin nécessite uniquement :

app.example.com  A  <IP de l'équilibreur de charge de la Gateway>

Le sous-domaine nécessite généralement :

app.example.com         A  <IP de l'équilibreur de charge de la Gateway>
cortex.example.com      A  <IP de l'équilibreur de charge de la Gateway>
agentic.example.com     A  <IP de l'équilibreur de charge de la Gateway>
ws-agentic.example.com  A  <IP de l'équilibreur de charge de la Gateway>
analytics.example.com   A  <IP de l'équilibreur de charge de la Gateway>
auth.example.com        A  <IP de l'équilibreur de charge de la Gateway>

Cette IP est celle publiée par le Service LoadBalancer de votre implémentation Gateway API — le chart ne provisionne jamais d'IP publique et tous les Services Scrydon restent ClusterIP.

Changer un déploiement actif

Provisionnez les enregistrements DNS et les certificats cibles.
Modifiez routing.mode et les valeurs d'hôte/URL publique correspondantes.
Mettez à niveau la même version du chart avec votre fichier de valeurs.
Vérifiez les listeners de la Gateway, les HTTPRoutes, les certificats, les états de santé, la connexion et les routes WebSocket.
Basculez le DNS. Les utilisateurs devront peut-être se reconnecter car la portée des cookies a changé.

helm upgrade scrydon oci://scrydonops.azurecr.io/scrydon/charts/scrydon \
  --version "${CURRENT_VERSION}" \
  --namespace scrydon-platform \
  -f values.customer.yaml \
  --wait

# Une seule Gateway dans les deux modes — vérifiez que ses listeners sont Programmed
kubectl get gateway -n scrydon-platform
kubectl describe gateway gateway-frontdoor -n scrydon-platform

# Sous-chemin : une HTTPRoute par application activée, portant ses préfixes de chemin
# Sous-domaine : une HTTPRoute par application activée, correspondant à / sur son nom d'hôte
kubectl get httproute -A

Revenir au mode précédent puis mettre à niveau effectue le retour arrière du routage. Cela n'affecte pas l'isolation des runtimes de notebooks, car Marimo reste derrière Analytics dans les deux modes.

Espaces de noms multiples

Une seule Gateway sert tous les espaces de noms, dans les deux modes de routage. Le rattachement d'une HTTPRoute à une Gateway d'un autre espace de noms est une opération de premier ordre : répartir les services via namespaces.* ne génère donc aucune porte d'entrée supplémentaire. gateway-frontdoor reste dans scrydon-platform, et l'HTTPRoute de chaque application vit à côté de son propre Service backend en pointant vers cette unique Gateway.

La Gateway admet les routes exactement des espaces de noms dans lesquels le chart génère ses ressources — son sélecteur allowedRoutes les liste par nom. Relancez donc helm upgrade après tout changement de namespaces.*, pour que le sélecteur suive les routes.

Le TLS est lui aussi centralisé. Chaque listener référence un Secret dans l'espace de noms de la Gateway : tls-frontdoor (ou gateway.tls.existingSecret) n'est créé que dans scrydon-platform, quelles que soient les valeurs de namespaces.agentic / namespaces.analytics / namespaces.cortex. Les copies de certificat par espace de noms et le contournement par réutilisation SNI de Traefik, nécessaires à la périphérie Ingress, ont disparu.