Pourquoi un Internal Developer Portal ?
Quand une startup grandit, les pratiques d'infrastructure qui fonctionnaient à cinq deviennent un frein à vingt. Les questions reviennent sans cesse : qui est responsable de ce service ? Où est la documentation ? Comment créer un nouveau microservice sans réinventer la roue ?
Un IDP répond à ces questions en offrant un point d'entrée unique pour les développeurs. Parmi les options disponibles, Backstage.io s'est imposé comme la référence open-source.
Backstage.io en bref
Backstage n'est pas un produit clé en main. C'est un framework basé sur React et Node.js sur lequel on construit son propre portail. Cette distinction est importante : il faut du temps d'ingénierie pour le déployer et le maintenir, mais la contrepartie est une personnalisation totale.
Les briques principales :
- Software Catalog : un registre centralisé de tous les services, avec propriétaire, dépendances et métadonnées
- TechDocs : la documentation vit dans le dépôt, Backstage la rend consultable
- Plugins : plus de 150 plugins communautaires (Kubernetes, ArgoCD, GitLab CI, Grafana, PagerDuty...)
- Software Templates : des modèles pour scaffolder de nouveaux projets avec les standards de l'organisation
Le contexte : une startup en croissance
Notre client est une startup d'une vingtaine de développeurs. L'infrastructure est sur GCP, les services tournent sur Kubernetes, le déploiement passe par ArgoCD.
Le problème : chaque équipe avait ses propres pratiques. La documentation était dispersée entre Notion, Confluence et des README oubliés. Personne ne savait précisément quels services tournaient en production ni qui en était responsable.
Ce que nous avons mis en place
1. Le Software Catalog
Le catalogue est le coeur de Backstage. Chaque service est déclaré via un fichier catalog-info.yaml à la racine de son dépôt :
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: api-payments
description: API de gestion des paiements
annotations:
backstage.io/kubernetes-id: api-payments
argocd/app-name: api-payments
backstage.io/techdocs-ref: dir:.
spec:
type: service
lifecycle: production
owner: team-backend
dependsOn:
- component:database-payments
Ce fichier déclare le service, son propriétaire, ses dépendances et les annotations nécessaires aux plugins Kubernetes et ArgoCD.
Pour bootstrapper le catalogue sans demander à chaque équipe d'ajouter le fichier manuellement, nous avons utilisé la découverte automatique des dépôts GitLab. Backstage scanne l'organisation et importe les entités trouvées.
2. TechDocs
Chaque service embarque sa documentation dans un dossier docs/ avec un fichier mkdocs.yml. La documentation est générée en CI (GitLab CI dans notre cas) et stockée dans un bucket GCS. Backstage la sert directement dans l'interface.
L'avantage : la doc est versionnée, révisée en merge request, et accessible au même endroit que le reste des informations sur le service.
3. Plugin Kubernetes
Le plugin Kubernetes affiche directement dans la page du service :
- L'état des pods (Running, CrashLoopBackOff, Pending...)
- Les événements récents
- Les logs
- Les ressources consommées
La configuration se fait dans app-config.yaml :
kubernetes:
serviceLocatorMethod:
type: multiTenant
clusterLocatorMethods:
- type: config
clusters:
- url: https://kubernetes.default.svc
name: production
authProvider: serviceAccount
serviceAccountToken: ${K8S_SA_TOKEN}
Le lien entre un service Backstage et ses ressources Kubernetes se fait via l'annotation backstage.io/kubernetes-id dans le catalog-info.yaml.
4. Plugin ArgoCD
Le plugin ArgoCD affiche le statut de synchronisation, l'historique des déploiements et la santé de l'application. Les développeurs voient en un coup d'oeil si leur dernière release est déployée et synchronisée.
Les difficultés rencontrées
Le rythme des mises à jour. Backstage publie une release par semaine. Prendre du retard rend les mises à jour douloureuses. Nous avons mis en place un pipeline dédié qui exécute backstage-cli versions:bump chaque semaine et ouvre une merge request automatique.
La migration vers le nouveau backend. Depuis fin 2024, Backstage pousse un nouveau système backend avec injection de dépendances. L'ancien est déprécié. La migration demande du travail, surtout si des plugins custom sont en place.
Le peuplement du catalogue. C'est le défi organisationnel, pas technique. Même avec la découverte automatique, les fichiers catalog-info.yaml générés sont incomplets. Il faut que chaque équipe enrichisse les métadonnées (owner, lifecycle, dépendances). Cela demande de l'accompagnement.
Les résultats
Après trois mois :
- 100% des services sont dans le catalogue avec un propriétaire identifié
- Le temps d'onboarding d'un nouveau développeur est passé de plusieurs jours à quelques heures
- Les développeurs consultent l'état de leurs déploiements et logs Kubernetes directement dans Backstage, sans accès direct au cluster
- La documentation est à jour et consultable depuis un seul endroit
Pour qui Backstage est-il adapté ?
Backstage demande un investissement initial significatif. Ce n'est pas la bonne solution pour toutes les organisations.
Il est pertinent si :
- Vous avez la capacité d'ingénierie pour le maintenir (au moins 1 à 2 personnes)
- Vous voulez un contrôle total sur votre portail
- Vous êtes déjà dans l'écosystème CNCF
- Vous valorisez l'open-source et l'absence de vendor lock-in
Pour les organisations qui veulent un résultat rapide sans dédier d'équipe, des alternatives SaaS comme Port ou OpsLevel peuvent être plus pragmatiques.
Conclusion
Backstage.io n'est pas un outil qu'on installe et qu'on oublie. C'est un investissement qui porte ses fruits quand il est traité comme un produit interne, avec une équipe dédiée et une adoption progressive. Commencer par le Software Catalog, prouver la valeur rapidement, puis étendre aux plugins et aux templates.
Pour notre client, le retour sur investissement a été net : moins de questions répétitives, une meilleure visibilité sur la production, et des développeurs plus autonomes.