ITSkillsCenter
Développement Web

Plateforme de développeur interne avec Backstage : architecture pour startup

21 min de lecture

Pourquoi une plateforme interne change tout dans une startup tech

Quand une startup passe de cinq à cinquante développeurs, une mutation silencieuse se produit. Les deux premières années, on déploie en SSH, on partage les mots de passe sur Slack, on documente sur Notion quand on y pense. Chaque ingénieur connaît tout le système et trouve les réponses en demandant au voisin. À partir d’une dizaine d’ingénieurs, ce modèle craque. La nouvelle recrue passe deux semaines à comprendre ce qui tourne où, l’équipe SRE devient un goulot d’étranglement parce qu’elle est seule à savoir provisionner un environnement, et la chasse aux dépendances cassées entre microservices vire au sport national.

Le Platform Engineering est la réponse industrialisée à ce point de bascule. L’idée centrale est simple : on construit une plateforme de développeur interne — Internal Developer Platform, abrégé IDP — qui transforme la complexité opérationnelle en self-service pour les équipes produit. À la place d’un ticket Jira « provisionne-moi une base PostgreSQL », un développeur clique sur un bouton, remplit un formulaire, et trois minutes plus tard une base est créée, monitorée, sauvegardée, branchée sur le secret manager, déclarée dans le catalogue de services et documentée. Tout ça sans qu’un humain de l’équipe infra ait fait quoi que ce soit.

Backstage est aujourd’hui la brique de référence pour matérialiser cette idée. Open source, créé chez Spotify en 2016 puis donné à la Cloud Native Computing Foundation en 2020 où il est devenu projet incubating, Backstage fournit le portail unifié, le catalogue de services et le moteur de génération de projets que l’on peut étendre par plugins. Ce guide pose l’architecture complète d’un IDP minimal viable construit autour de Backstage, avec les choix techniques argumentés et le chemin de mise en place que peut suivre une startup de quinze à cent ingénieurs. Les tutoriels pas-à-pas pour chaque brique sont liés au fil du texte.

Sommaire

Platform engineering : la promesse et les limites

Le terme platform engineering a explosé entre 2022 et 2024 sous l’impulsion de Gartner qui l’a placé dans son Hype Cycle, mais le concept couvert est ancien. Spotify documente sa Backstage interne dès 2016, Netflix expose son Paved Road en 2018, Mercado Libre, Adidas, American Airlines et HSBC ont publié des retours d’expérience sur leurs plateformes internes au cours des années qui ont suivi. Le constat partagé est que sans plateforme dédiée, le cognitive load imposé aux équipes produit explose : un développeur senior qui doit comprendre Kubernetes, Terraform, Vault, Prometheus, Grafana, Helm, ArgoCD, GitHub Actions, le mesh de service, les politiques OPA et la roadmap sécurité en plus de son métier perd un temps fou pour livrer la moindre fonctionnalité.

La promesse du platform engineering tient en une phrase : un développeur produit ne devrait jamais avoir à apprendre l’infrastructure pour livrer une fonctionnalité standard. La plateforme propose des chemins balisés — les golden paths — qui couvrent quatre-vingts pour cent des besoins standards. Le développeur reste libre de sortir des sentiers s’il a un cas spécifique, mais la valeur par défaut est de prendre le chemin tracé. Cette philosophie est documentée dans le Team Topologies de Matthew Skelton et Manuel Pais qui distinguent les stream-aligned teams (les équipes produit) des platform teams (les équipes plateforme), avec une interaction codifiée en X-as-a-Service.

Les limites sont réelles et il faut les nommer. Construire une plateforme coûte cher en ingénieurs et en temps, et la valeur ne se voit qu’au bout de plusieurs mois. Une startup de cinq personnes n’a pas besoin d’un IDP, elle a besoin de livrer son produit. Une startup de quinze personnes commence à en sentir l’utilité, vingt-cinq la rend indispensable. La règle empirique partagée par les équipes plateforme matures est qu’on commence à investir sur la plateforme quand le ratio temps passé sur l’infra dépasse trente pour cent du temps des développeurs produit. En dessous, l’investissement ne se rentabilise pas. Au-dessus, chaque mois sans plateforme est un mois perdu.

L’architecture Backstage en quatre couches

Backstage n’est pas un produit fini. C’est un framework de portail développeur livré comme un monorepo TypeScript que l’on installe sur son infrastructure, que l’on configure et que l’on étend par plugins. Cette nature explique à la fois sa puissance et sa courbe d’apprentissage : on n’achète pas Backstage, on le construit. La branche stable au mois de mai 2026 est la 1.50.x — la dernière version publiée au moment de la rédaction est la v1.50.4 du 29 avril 2026 — et les prérequis officiels sont Node.js 22 ou 24 (Active LTS), Yarn 4.4.1, Docker, Git, six gigaoctets de RAM et vingt gigaoctets de disque pour l’environnement de développement.

L’architecture se décompose en quatre couches qu’il faut comprendre avant de toucher à la moindre ligne de configuration. La couche frontend est une application React qui fournit le portail web : pages d’accueil, navigation, composition des plugins. La couche backend est un serveur Node.js qui expose les API consommées par le frontend, fait tourner les processeurs de catalogue, exécute les actions du scaffolder et traite la documentation. La couche plugins est l’écosystème extensible : un plugin Backstage est un module npm qui apporte une fonctionnalité — intégration GitHub, intégration Kubernetes, intégration ArgoCD, intégration PagerDuty, intégration SonarQube. La couche configuration est centralisée dans un fichier app-config.yaml qui pilote tout le reste.

Le frontend et le backend communiquent par HTTP. En développement local, le frontend tourne sur le port 3000 et le backend sur le port 7007. En production, on les déploie typiquement dans deux pods Kubernetes derrière un ingress unique. La base de données par défaut est SQLite pour le développement, et PostgreSQL dès qu’on dépasse le bac à sable. Le catalogue stocke ses entités, le scaffolder ses tâches en cours et leur historique, l’authentification les sessions. La RAM consommée en production dépend du nombre d’entités dans le catalogue : une organisation avec deux mille services et cinq cents personnes tient confortablement dans deux gigaoctets côté backend.

Avant de plonger dans la mise en place, l’étape zéro est de faire tourner Backstage en local et de comprendre la structure du monorepo généré. Le tutoriel d’installation pas-à-pas couvre la création de l’application avec npx @backstage/create-app@latest, la configuration des variables d’environnement et le premier lancement avec yarn dev.

Les golden paths comme pacte de la plateforme

Un golden path est un chemin recommandé pour accomplir une tâche standard de développement. Concrètement, c’est la combinaison d’un template de projet (créé dans le scaffolder), d’une documentation de référence (publiée dans TechDocs) et d’une intégration prête à l’emploi avec les outils internes (CI/CD configurée, observabilité branchée, secrets gérés, déploiement automatisé). Le développeur qui suit le golden path obtient en quelques minutes un service production-ready qui respecte toutes les conventions de l’organisation.

Les golden paths typiques d’une startup tech tournent autour de quatre à sept patterns selon la maturité. Microservice HTTP en Node.js avec Fastify, microservice HTTP en Go avec chi, worker asynchrone consommant un topic Kafka, application frontend React, fonction serverless courte sur AWS Lambda, job batch piloté par un cron — voilà un panel raisonnable. Chacun de ces patterns devient un template scaffolder qui produit un repository GitHub déjà configuré : pipeline CI qui compile, teste et publie l’image Docker, manifests Kubernetes pré-remplis, fichier catalog-info.yaml qui enregistre le service dans le catalogue, dossier docs/ avec un squelette de documentation TechDocs, fichier README qui explique comment développer.

Le pacte de la plateforme avec les équipes produit s’énonce simplement. Si vous suivez le golden path, on s’occupe de tout : sécurité, observabilité, conformité, mise à jour des dépendances, migration des outils internes. Si vous décidez de sortir du sentier balisé, c’est votre droit, mais c’est à votre charge. Cette asymétrie crée l’incitation positive à utiliser la plateforme sans rendre son usage obligatoire. Forcer l’usage est un anti-pattern documenté qui mène les équipes produit à contourner la plateforme et à pourrir l’ambiance — la plateforme doit gagner en s’utilisant.

Le Software Catalog : la source de vérité

Le Software Catalog est le cœur de Backstage. C’est une base de données graphe qui décrit l’organisation technique : quels services existent, qui les possède, à quel domaine métier ils appartiennent, quelles API ils exposent, quelles ressources d’infrastructure ils consomment, quelles équipes en sont responsables. Cette information n’est pas saisie dans une interface, elle est déclarée dans des fichiers YAML versionnés à côté du code de chaque service, ce qui change tout : le catalogue ne se désynchronise pas, parce qu’il vit dans le repository qui contient la vérité.

Le format de description est documenté dans la spec officielle. Chaque entité est un document YAML qui suit le pattern apiVersion / kind / metadata / spec. Les huit kinds principaux sont Component (un service ou une application), API (une interface exposée — REST, gRPC, AsyncAPI, GraphQL), Resource (une infrastructure — base de données, bucket S3, file de messages), System (un regroupement cohérent de Components et Resources), Domain (un regroupement de Systems autour d’une logique métier), Group (une équipe ou business unit), User (une personne) et Location (un pointeur vers d’autres descripteurs).

Le tutoriel dédié Software Catalog Backstage : référencer ses services avec catalog-info.yaml détaille la rédaction de chaque kind, les relations entre entités et la stratégie d’enregistrement automatique via un dossier de pointeurs. Le pattern recommandé est qu’un fichier catalog-info.yaml vit à la racine de chaque repository et que Backstage va le lire automatiquement par le mécanisme de discovery sur l’organisation GitHub. Cette approche fait du repository la source de vérité et élimine toute saisie manuelle.

La valeur du catalogue se révèle quand on en exploite les relations. Un service apparaît avec ses APIs exposées, ses APIs consommées, son équipe propriétaire, ses dashboards Grafana liés, son canal Slack, sa documentation, son repository, ses pull requests ouvertes, ses alertes en cours. Un nouveau développeur arrive et a en cinq minutes la cartographie technique qu’il aurait mis trois semaines à reconstruire en interrogeant ses collègues. Une équipe SRE qui investigue un incident voit immédiatement les dépendances amont et aval du service en panne.

Le scaffolder : génération de projets opinionnée

Le scaffolder est le moteur d’exécution des golden paths. Il consomme des templates écrits en YAML — au format scaffolder.backstage.io/v1beta3 — qui décrivent un formulaire utilisateur (les parameters) et une suite d’étapes à exécuter (les steps). Le développeur ouvre la page « Create » du portail Backstage, choisit son template, remplit le formulaire, clique sur « Create », et le scaffolder fait le reste : il télécharge un dossier de fichiers modèles, applique les valeurs du formulaire dans les placeholders Nunjucks, crée un repository GitHub avec ces fichiers, et enregistre le nouveau service dans le catalogue.

Les actions disponibles sont nombreuses et extensibles. Les actions de base sont fetch:template pour récupérer et templater un dossier de fichiers, fetch:plain pour télécharger sans templating, publish:github pour créer un repository GitHub (variantes pour GitLab, Bitbucket, Azure DevOps), catalog:register pour déclarer la nouvelle entité dans le Software Catalog. Une organisation mature ajoute ses propres actions custom : provisionner une base de données, créer un secret dans Vault, ouvrir un canal Slack, tagger l’équipe owner dans le repo. Le tutoriel Scaffolder Backstage : créer un template de microservice Node.js construit pas-à-pas un template complet pour un microservice Fastify, depuis le formulaire jusqu’à l’enregistrement automatique.

Le bénéfice est massif. Sans scaffolder, le démarrage d’un nouveau service prenait deux à cinq jours d’ingénieur senior — créer le repository, copier la config CI d’un autre service, ajuster les manifests Kubernetes, configurer l’observabilité, écrire les premières lignes de README. Avec un golden path scaffolder, le démarrage prend cinq minutes. Sur une organisation qui crée vingt nouveaux services par an, c’est plus de cinquante jours-homme économisés et — bien plus important — la garantie que tous ces services partagent les mêmes conventions, les mêmes versions, les mêmes patterns de sécurité.

TechDocs : la documentation au plus près du code

TechDocs résout un problème universel : la documentation technique pourrit dès qu’elle s’éloigne du code. La solution Backstage est radicale et inspirée du docs-as-code : la documentation d’un service vit dans son propre repository, écrite en Markdown dans un dossier docs/, avec un fichier mkdocs.yml à la racine. Backstage la récupère, la fait passer à travers MkDocs avec un thème dédié, et la sert dans le portail. La doc est versionnée avec le code, revue dans les pull requests, et n’a aucune chance de dériver.

La configuration officielle est exposée dans la documentation TechDocs. Trois choix structurants se présentent. Le builder peut être local (Backstage compile à la volée) ou external (on compile en CI et on publie l’artefact). Le generator tourne dans Docker (par défaut) ou directement avec une installation locale de MkDocs. Le publisher stocke les artefacts compilés dans le système de fichiers local, dans un bucket Amazon S3, dans Google Cloud Storage ou dans Azure Blob Storage. La combinaison recommandée pour la production est builder external + publisher S3, avec un job CI qui compile la doc à chaque merge sur main et la pousse dans le bucket.

Le tutoriel TechDocs Backstage : documenter ses services avec MkDocs décrit l’installation des paquets Python mkdocs et mkdocs-techdocs-core, le squelette du fichier mkdocs.yml, l’annotation backstage.io/techdocs-ref: dir:. à ajouter dans le catalog-info.yaml de chaque service, et la configuration du builder externe avec un job GitHub Actions qui compile la doc et la publie dans S3.

Construire un IDP minimal viable en six semaines

Le piège classique est de viser trop large dès le départ. Une équipe plateforme nouvellement constituée passe ses trois premiers mois à construire une plateforme parfaite que personne n’utilise. La méthode qui marche est inverse : on livre une plateforme minuscule mais utilisable en six semaines, on l’éprouve avec une équipe pilote, on corrige et on étend par incrément. Voici un plan calibré pour une startup de vingt à cinquante développeurs.

Semaine 1 — Backstage en local et en staging. Installation, configuration de l’authentification GitHub OAuth, déploiement sur un cluster Kubernetes existant via le chart Helm officiel. Au bout de la semaine, l’équipe plateforme a une instance fonctionnelle accessible aux développeurs internes, sans données.

Semaine 2 — Software Catalog avec auto-discovery GitHub. Activation de l’intégration GitHub avec un Personal Access Token ou une GitHub App, configuration du processeur de discovery sur l’organisation, ajout d’un fichier catalog-info.yaml dans cinq services pilotes. Au bout de la semaine, le portail montre cinq services avec leurs propriétaires, leurs APIs et leurs dépendances.

Semaine 3 — Premier golden path. Construction d’un template scaffolder pour le pattern le plus fréquent (typiquement microservice HTTP), avec génération automatique du repo, du pipeline CI, des manifests Kubernetes et du catalog-info.yaml. Test avec une équipe pilote sur un service réel.

Semaine 4 — TechDocs en mode builder local. Activation de TechDocs sur les cinq services pilotes, écriture des squelettes de documentation, démonstration du rendu dans le portail. Le mode local suffit pour cette phase, l’externalisation viendra ensuite.

Semaine 5 — Intégration observabilité et alerting. Plugin Grafana qui affiche les dashboards par service, plugin PagerDuty qui montre les alertes en cours, plugin GitHub qui liste les pull requests ouvertes. Le portail devient le hub où un développeur trouve tout ce qui concerne un service.

Semaine 6 — Onboarding et documentation interne. Rédaction du guide d’utilisation pour les développeurs, animation d’ateliers pour les équipes pilotes, mesure des premiers indicateurs (temps de création d’un service, nombre de services référencés, nombre de templates utilisés). À la fin de cette semaine, l’IDP minimal est en production et trois équipes l’utilisent quotidiennement.

Au-delà des six semaines, la roadmap typique enchaîne deuxième et troisième golden paths, deuxième source d’authentification (OIDC d’entreprise), enrichissement du catalogue avec les annotations Kubernetes pour lier les services à leurs déploiements, plugin de coût cloud, plugin de revue de sécurité, déclinaison sur l’écosystème data (templates de pipelines Airflow ou Dagster, catalogue de datasets).

Dimensionner l’équipe plateforme

Une équipe plateforme dédiée commence à exister à partir de trois ingénieurs. En dessous, on a une personne référente qui porte la plateforme à temps partiel, ce qui est viable jusqu’à environ quinze développeurs servis. Le seuil critique est qu’une équipe plateforme doit pouvoir aller en réunion à deux personnes pendant qu’une troisième tient le support, sinon elle se transforme en service desk et perd sa capacité à construire. Au-dessus de cinquante développeurs servis, deux à trois ingénieurs plateforme par tranche de cinquante développeurs est un ordre de grandeur raisonnable.

Les profils recherchés mélangent compétences en infrastructure (Kubernetes, observabilité, IaC), en backend (Node.js et TypeScript pour Backstage, Python ou Go pour les outils annexes) et en produit. Ce dernier point est le plus négligé : une équipe plateforme est une équipe produit dont les utilisateurs sont les autres équipes de l’entreprise. Les bonnes pratiques produit s’appliquent — interviews utilisateurs, mesure de l’usage, cycles de feedback courts, communication du backlog. La pire posture est l’équipe plateforme qui livre par injonction sans demander à personne ce dont les développeurs ont besoin.

Mesurer l’impact d’une plateforme

Sans métriques, une plateforme dérive et devient un objet politique difficile à défendre au moment des coupes budgétaires. Quatre familles d’indicateurs cohabitent. Les indicateurs d’adoption mesurent à quel point la plateforme est utilisée — nombre d’utilisateurs actifs hebdomadaires sur le portail, nombre de services référencés dans le catalogue, nombre de templates exécutés par mois, ratio des nouveaux services créés via golden path versus créés à la main.

Les indicateurs de productivité reprennent le cadre DORA (DevOps Research and Assessment) publié par Google : fréquence de déploiement, lead time du commit à la production, taux d’échec des changements, temps moyen de restauration. Une bonne plateforme déplace ces métriques dans le bon sens, en particulier le lead time qui chute spectaculairement quand le démarrage d’un service passe de jours à minutes.

Les indicateurs d’expérience développeur reposent sur des sondages réguliers — le SPACE framework de Microsoft Research formalise ce volet — qui mesurent satisfaction, performance perçue, activité, communication et efficacité. Le score Net Promoter Score interne sur la plateforme est un indicateur résumé utile.

Les indicateurs économiques rapportent le coût de l’équipe plateforme aux gains mesurés. Un calcul simple : combien de jours-homme l’équipe plateforme économise-t-elle par mois grâce à l’automatisation et aux golden paths, multiplié par le coût-jour moyen, comparé au salaire chargé de l’équipe plateforme. Les calculs honnêtes montrent un retour positif à partir de soixante à quatre-vingts développeurs servis, parfois plus tôt si l’organisation crée beaucoup de nouveaux services.

Erreurs fréquentes

Erreur Cause Solution
Construire la plateforme sans utilisateurs pilotes Vouloir tout finir avant de montrer Livrer une version maigre en six semaines avec deux équipes pilotes, itérer ensuite
Forcer l’usage de la plateforme Pression hiérarchique pour justifier l’investissement Rendre l’usage attractif par les golden paths, accepter les sorties de chemin
Catalogue saisi à la main Méconnaissance de l’auto-discovery Activer le processeur GitHub discovery, faire vivre le YAML dans chaque repo
Tout miser sur Backstage et négliger la doc interne Le portail ne se documente pas tout seul Écrire un guide d’onboarding plateforme, animer des ateliers réguliers
Sous-dimensionner l’équipe plateforme Vue de la plateforme comme projet ponctuel Trois ingénieurs minimum, trajectoire pérenne, posture produit
Mélanger autorisation et catalogue Confusion entre Backstage et IAM Backstage référence, l’IAM autorise — chacun son rôle
Ignorer les coûts cachés (PostgreSQL, S3, monitoring) Focus sur les ingénieurs, oubli du run Provisionner dès le départ une base PostgreSQL HA et un budget storage TechDocs

FAQ

Backstage est-il adapté à une startup de moins de vingt développeurs ?
Probablement pas. En dessous de quinze ingénieurs, la communication directe résout encore les problèmes que résout Backstage. L’investissement en temps de mise en place et de maintenance ne se rentabilise pas. La règle simple est de ne lancer le chantier qu’à partir du moment où le ratio temps infrastructure dépasse trente pour cent du temps développeur produit.

Quelle est la différence entre Backstage et Port ou Cortex ?
Backstage est open source et auto-hébergé, ce qui maximise la flexibilité et minimise le coût récurrent au prix d’un investissement initial en construction et maintenance. Port et Cortex sont des solutions SaaS commerciales qui proposent un IDP clé en main — moins flexibles, plus rapides à mettre en place, modèle payant à l’utilisateur. Le choix dépend du goût pour l’ingénierie maison et du budget récurrent disponible.

Faut-il connaître TypeScript pour utiliser Backstage ?
Pour utiliser Backstage en consommateur, non — les développeurs produit interagissent avec le portail web et n’écrivent que du YAML. Pour étendre Backstage avec des plugins custom, oui — TypeScript est le langage du projet. Une équipe plateforme sans aucune compétence TypeScript se limitera aux plugins existants, ce qui couvre déjà beaucoup de cas standards.

Backstage tient-il en production avec quelques milliers de services ?
Oui. Spotify fait tourner sa propre instance avec plusieurs dizaines de milliers d’entités, et plusieurs grandes organisations ont publié des retours d’expérience à des échelles similaires. Le facteur limitant en pratique est PostgreSQL — il faut une base correctement dimensionnée et un suivi des index — plus que Backstage lui-même.

Comment gérer l’authentification dans Backstage ?
Backstage supporte nativement GitHub, GitLab, Google, Microsoft, Okta, Auth0 et tout fournisseur OIDC ou SAML. La pratique recommandée est de brancher Backstage sur le fournisseur d’identité de l’entreprise dès le déploiement de production, et de mapper les groupes du fournisseur sur les Groups du Software Catalog pour aligner ownership et permissions.

Le code de Backstage est-il maintenu activement ?
Oui. Backstage publie une version mineure toutes les deux semaines en moyenne, le projet est utilisé par plusieurs centaines d’organisations identifiées et le repository GitHub officiel backstage/backstage est l’un des projets les plus actifs de la CNCF. Le rythme de mise à jour est rapide — il faut prévoir une montée de version trimestrielle dans la roadmap de l’équipe plateforme.

Peut-on utiliser Backstage uniquement pour la documentation ?
Techniquement oui, en activant TechDocs et en ignorant les autres plugins. Économiquement, ça revient à acheter une voiture pour ne s’en servir que comme parapluie : le coût de mise en place de Backstage ne se justifie que si on en exploite au moins le catalogue et idéalement le scaffolder.

Références officielles

Tutoriels associés

#Backstage #cluster-pillar #cluster-platform-engineering #IDP #Platform Engineering #Software Catalog
Sponsoriser ce contenu

Cet emplacement est à vous

Position premium en fin d'article — c'est l'instant où les lecteurs sont le plus engagés. Réservez cet espace pour votre marque, votre formation ou votre offre.

Recevoir nos tarifs
Publicité

Articles Similaires