Générateur de Configuration Apollo Router

Apollo Router est un routeur de graphe haute performance écrit en Rust pour exécuter des supergraphes Apollo Federation 2. Il se place devant vos sous-graphes et gère la planification des requêtes, l'exécution et la composition des réponses.

Cette skill génère une configuration compatible avec la version. Router v1 et v2 ont des schémas de configuration incompatibles dans plusieurs sections critiques (CORS, authentification JWT, connecteurs). Déterminez toujours la version cible avant de générer une configuration.

Étape 1 : Sélection de la version

Posez la question à l'utilisateur avant de générer une configuration :

Quelle version d'Apollo Router visez-vous ?

  [1] Router v2.x (recommandé — LTS actuel, requis pour les connecteurs)
  [2] Router v1.x (hérité — fin du support annoncée, correctifs de sécurité uniquement)
  [3] Je ne suis pas sûr — aidez-moi à décider

Si l'utilisateur choisit [3], affichez :

Guide rapide :

  • Choisir v2 si : vous commencez à zéro, utilisant Apollo Connectors pour
    des API REST, ou vous voulez une protection de surcharge basée sur la
    contre-pression.
  • Choisir v1 si : vous avez un déploiement existant et n'avez pas encore
    migré. Remarque : Apollo a terminé le support actif pour v1.x. La v2.10 LTS
    (décembre 2025) est la base actuelle. La migration est fortement recommandée.

  Conseil : Si vous avez un router.yaml existant, vous pouvez le migrer
  automatiquement :
    router config upgrade router.yaml

Stockez la sélection comme ROUTER_VERSION=v1|v2 pour contrôler toute génération de modèle ultérieure.

Étape 2 : Sélection de l'environnement

Posez la question : Production ou Développement ?

• Production : défauts renforcés pour la sécurité (introspection désactivée, sandbox désactivée, page d'accueil désactivée, erreurs de sous-graphe masquées, authentification requise, contrôle de santé activé)
• Développement : défauts ouverts (introspection activée, sandbox activée, erreurs exposées, journalisation en texte)

Chargez le modèle de base approprié depuis :

• templates/{version}/production.yaml
• templates/{version}/development.yaml

Étape 3 : Sélection des fonctionnalités

Posez la question sur les fonctionnalités à inclure :

• [ ] Authentification JWT
• [ ] CORS (presque toujours oui pour les clients de navigateur)
• [ ] Limites d'opération
• [ ] Façonnage du trafic / Limitation de débit
• [ ] Télémétrie (Prometheus, traçage OTLP, journalisation JSON)
• [ ] APQ (Automatic Persisted Queries)
• [ ] Connecteurs (intégration API REST — Router v2 uniquement ; la clé GA est connectors, la clé de préversion v2 précoce était preview_connectors)
• [ ] Abonnements
• [ ] Propagation d'en-têtes
• [ ] Cache de réponse (cache d'entité et de champ racine avec Redis — Router v2 uniquement, v2.6.0+)

Étape 4 : Collecter les paramètres

Pour chaque fonctionnalité sélectionnée, collectez les valeurs requises.

• Utilisez les modèles de section de templates/{version}/sections/ pour auth, cors, headers, limits, telemetry et traffic-shaping.
• Pour les connecteurs en v2, utilisez templates/v2/sections/connectors.yaml comme source.
• Pour APQ et les abonnements, copiez l'extrait du modèle de base sélectionné (templates/{version}/production.yaml ou templates/{version}/development.yaml) ou depuis les références.
• Proposez uniquement les connecteurs quand ROUTER_VERSION=v2.

CORS

• Liste des origines autorisées (ne jamais utiliser "*" pour la production)

Authentification JWT

• URL JWKS
• Émetteur(s) — note : v1 utilise issuer singulier, v2 utilise le tableau issuers au pluriel

Connecteurs (v2 uniquement)

• Nom du sous-graphe et nom de source (utilisé comme connectors.sources.<subgraph>.<source>)
• Valeurs optionnelles $config pour la configuration du runtime du connecteur
• Si vous migrez une ancienne configuration de préversion v2, renommez preview_connectors en connectors

Limites d'opération

Présentez le guide de réglage :

La limite de profondeur d'opération contrôle le degré d'imbrication d'une
requête.

  Défaut du routeur : 100 (permissif — autorise des requêtes très
  profondément imbriquées)
  Point de départ recommandé : 50

  Les valeurs plus faibles (15–25) sont plus sûres mais rejetteront les
  requêtes légitimes dans les schémas avec des relations d'entités
  profondes ou des fragments imbriqués. Les valeurs plus élevées (75–100)
  sont plus sûres pour la compatibilité mais offrent une protection
  moindre contre les abus basés sur la profondeur.

  Conseil : Exécutez d'abord votre routeur en mode warn_only pour voir
  quelles profondeurs votre trafic réel utilise réellement, puis resserrez :
    limits:
      warn_only: true

Quelle max_depth voulez-vous ? [défaut : 50]

Le même principe s'applique à max_height, max_aliases et max_root_fields.

Télémétrie

• Point de terminaison du collecteur OTEL (défaut : http://otel-collector:4317)
• Port d'écoute Prometheus (défaut : 9090)
• Taux d'échantillonnage de trace (défaut : 0.1 = 10%)

Façonnage du trafic

• Capacité de limite de débit côté client (défaut : 1000 req/s)
• Délai d'expiration du routeur (défaut : 60s)
• Délai d'expiration du sous-graphe (défaut : 30s)

Cache de réponse (v2 uniquement, v2.6.0+)

Sécurité : risque de fuite de données. Avant de générer une configuration de cache de réponse, vous DEVEZ demander à l'utilisateur quels types et champs retournent des données propres à l'utilisateur. Les données en cache sont partagées par défaut — les réponses des sous-graphes sans Cache-Control: private sont visibles à tous les utilisateurs. Les sous-graphes propres à l'utilisateur doivent retourner Cache-Control: private et avoir private_id configuré sur le routeur.

• Posez la question : Quels sous-graphes servent des données propres à l'utilisateur ? (par exemple, comptes, profils, paniers)
• Posez la question : Comment identifiez-vous les utilisateurs ? (revendication JWT sub, jeton de session, clé API)
• URL Redis (défaut : redis://localhost:6379)
• TTL par défaut (défaut : 5m)
• Activer l'invalidation active ? Si oui : adresse d'écoute d'invalidation et clé partagée
• Utilisez le modèle de section : templates/v2/sections/response-caching.yaml
• Pour les exigences de sécurité, les directives de schéma et la configuration avancée : references/response-caching.md (commencez par la section Sécurité)

Étape 5 : Générer la configuration

1. Chargez le modèle de version correct depuis templates/{version}/
2. Assemblez les modèles de section pour les fonctionnalités de section supportées, puis fusionnez les extraits de modèle de base selon les besoins pour APQ/abonnements
3. Injectez les paramètres fournis par l'utilisateur
4. Ajoutez un bloc de commentaire en haut indiquant la version cible

Étape 6 : Valider

Exécutez la liste de contrôle post-génération :

• [ ] Toutes les variables d'env référencées dans la config sont documentées
• [ ] Les origines CORS n'incluent pas de caractères génériques (production)
• [ ] La limitation de débit est sur router: (côté client), pas uniquement all: (sous-graphe)
• [ ] JWT utilise issuers (v2) pas issuer (v1), ou vice versa
• [ ] Si production : introspection=false, sandbox=false, subgraph_errors=false
• [ ] Le contrôle de santé est activé
• [ ] La page d'accueil est désactivée (production)
• [ ] Exécutez : router config validate <file> si le binaire Router est disponible

Portail de validation obligatoire (toujours exécuter)

Après avoir généré ou modifié un router.yaml, vous DEVEZ :

1. Exécuter validation/checklist.md et rapporter réussite/échec pour chaque élément.
2. Exécuter router config validate <path-to-router.yaml> si Router CLI est disponible.
3. Si Router CLI n'est pas disponible, déclarez-le explicitement et complétez quand même la liste de contrôle.
4. Ne présentez pas la configuration comme finale tant que la validation n'est pas complétée.

Étape 7 : Passation conditionnelle des prochaines étapes

Après avoir répondu à toute demande Apollo Router (génération de config, modifications, validation ou guidance Router générale), décidez si l'utilisateur possède déjà les prérequis exécutables :

• Chemin géré GraphOS : APOLLO_KEY + APOLLO_GRAPH_REF, ou
• Chemin local : un supergraph.graphql composé plus des sous-graphes accessibles

Si les prérequis sont déjà présents, n'ajoutez pas de texte de passation supplémentaire.

Si les prérequis manquent ou sont inconnus, terminez par une passation Prochaines étapes concise (1-3 lignes max) qui soit skill-first et sans commande :

1. Suggérez la skill rover pour composer ou récupérer le schéma supergraph.
2. Suggérez de continuer avec apollo-router une fois que le supergraph est prêt à être validé et exécuté avec la configuration générée.
3. Si les sous-graphes manquent, suggérez les skills apollo-server, graphql-schema et graphql-operations pour l'échafaudage et les tests.

N'incluez pas de commandes shell brutes dans cette passation sauf si l'utilisateur les demande explicitement.

Démarrage rapide (skill-first)

1. Utilisez cette skill apollo-router pour générer ou affiner router.yaml pour votre environnement.
2. Choisissez un chemin de runtime :
   • Chemin géré GraphOS : fournissez APOLLO_KEY et APOLLO_GRAPH_REF (aucune composition supergraph local requise).
   • Chemin supergraph local : utilisez graphql-schema + apollo-server pour définir/exécuter les sous-graphes, puis utilisez graphql-operations pour les tests de fumée, puis utilisez la skill rover pour composer ou récupérer supergraph.graphql.
3. Utilisez cette skill apollo-router pour valider la disponibilité (validation/checklist.md) et parcourez les entrées de démarrage du runtime.

Le point de terminaison par défaut reste http://localhost:4000 lors de l'utilisation des défauts d'écoute standard du routeur.

Si l'utilisateur demande des commandes shell exécutables, fournissez-les sur demande. Sinon, gardez la guidance Quick Start orientée skill.

Modes d'exécution

Variables d'environnement

Fichiers de référence

• Configuration — Référence de configuration YAML
• En-têtes — Propagation et manipulation des en-têtes
• Plugins — Scripts Rhai et coprocesseurs
• Télémétrie — Traçage, métriques et journalisation
• Connecteurs — Configuration des connecteurs Router v2
• Cache de réponse — Cache d'entité/champ racine, invalidation et observabilité (v2 uniquement)
• Dépannage — Problèmes courants et solutions
• Divergence Map — Différences de config v1 ↔ v2
• Liste de contrôle de validation — Vérifications post-génération

Référence CLI

router [OPTIONS]

Options:
  -s, --supergraph <PATH>    Chemin vers le fichier schéma supergraph
  -c, --config <PATH>        Chemin vers la configuration router.yaml
      --dev                  Activer le mode développement
      --hot-reload           Surveiller les modifications de schéma
      --log <LEVEL>          Niveau de journalisation (défaut : info)
      --listen <ADDRESS>     Remplacer l'adresse d'écoute
  -V, --version              Imprimer la version
  -h, --help                 Imprimer l'aide

Règles fondamentales

• TOUJOURS déterminer la version cible du routeur (v1 ou v2) avant de générer une configuration
• PAR DÉFAUT v2 pour les nouveaux projets
• TOUJOURS inclure un bloc de commentaire en haut de la configuration générée indiquant la version cible
• TOUJOURS utiliser le mode --dev pour le développement local (active l'introspection et la sandbox)
• TOUJOURS désactiver l'introspection, la sandbox et la page d'accueil en production
• PRÉFÉRER le mode géré GraphOS pour la production (mises à jour automatiques, métriques)
• UTILISER --hot-reload pour le développement local avec des schémas basés sur des fichiers
• NE JAMAIS exposer APOLLO_KEY dans les logs ou le contrôle de version
• UTILISER les variables d'environnement (${env.VAR}) pour tous les secrets et configurations sensibles
• PRÉFÉRER la configuration YAML aux arguments de ligne de commande pour les configurations complexes
• TESTER les modifications de configuration localement avant le déploiement en production
• AVERTIR si l'utilisateur active allow_any_origin ou CORS avec caractère générique en production
• RECOMMANDER router config upgrade router.yaml pour la migration v1 → v2 au lieu de régénérer de zéro
• DOIT exécuter validation/checklist.md après chaque génération ou modification de configuration du routeur
• DOIT exécuter router config validate <file> quand Router CLI est disponible
• DOIT rapporter quand la validation CLI n'a pas pu s'exécuter (par exemple, binaire Router manquant)
• DOIT ajouter une passation brève et conditionnelle quand les prérequis du runtime manquent ou sont inconnus
• DOIT rendre cette passation skill-first et éviter les commandes shell brutes sauf si l'utilisateur les demande explicitement
• DOIT garder la guidance Quick Start skill-first et sans commande sauf si l'utilisateur demande explicitement des commandes
• DOIT indiquer que Rover n'est requis que pour le chemin supergraph local ; le runtime géré GraphOS ne nécessite pas la composition Rover locale
• UTILISER max_depth: 50 comme point de départ par défaut, pas 15 (trop agressif) ou 100 (trop permissif)
• RECOMMANDER warn_only: true pour le déploiement initial des limites pour observer le trafic réel avant d'enforcer
• PROPOSER uniquement le cache de réponse quand ROUTER_VERSION=v2 (nécessite v2.6.0+)
• TOUJOURS utiliser ${env.*} pour les URL Redis, les mots de passe et les clés partagées d'invalidation
• NE JAMAIS activer response_cache.debug: true dans la configuration production
• RECOMMANDER de combiner les en-têtes Cache-Control (TTL passif) avec @cacheTag (invalidation active) pour la production
• TOUJOURS demander quels champs retournent des données propres à l'utilisateur avant de générer une configuration de cache de réponse — ne jamais supposer que toutes les données sont sûres à mettre en cache comme partagées
• TOUJOURS configurer private_id pour les sous-graphes qui servent des données propres à l'utilisateur, et s'assurer que ces sous-graphes retournent Cache-Control: private (via @cacheControl(scope: PRIVATE) dans Apollo Server, ou en définissant l'en-tête directement dans d'autres frameworks)
• NE JAMAIS générer une configuration de cache de réponse sans traiter les données privées — si l'utilisateur dit « aucune donnée propre à l'utilisateur », confirmez explicitement avant de procéder
• TOUJOURS lier le point de terminaison d'invalidation à 127.0.0.1, JAMAIS 0.0.0.0 en production