Adopter Backstage pour centraliser la découverte des services d’une organisation résout un vrai problème (savoir qui possède quoi, où trouver la documentation, quel est le statut de production d’un service), mais la valeur de cette centralisation dépend entièrement de la fraîcheur des données du catalogue, un problème d’organisation bien plus que d’outillage.

Ce que Backstage centralise réellement

Backstage agrège les métadonnées de chaque service (propriétaire, dépendances, liens vers la documentation, statut de production) à partir d’un fichier catalog-info.yaml déposé dans le dépôt de chaque service, plutôt que de découvrir cette information dynamiquement depuis l’infrastructure elle-même.

# catalog-info.yaml : la source de vérité du catalogue,
# maintenue manuellement dans chaque dépôt de service
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Traite les paiements et remboursements
spec:
  type: service
  owner: team-payments
  lifecycle: production

Le piège : une source de vérité déclarative, pas observée

Contrairement à un système qui interrogerait directement l’infrastructure en temps réel (Kubernetes, un registre de conteneurs), le catalogue Backstage reflète ce qu’un fichier YAML déclare, pas ce qui tourne réellement en production. Un service dont l’équipe propriétaire a changé, dont le statut est passé de « expérimental » à « production », ou qui a été purement et simplement décommissionné continue d’apparaître dans le catalogue exactement comme avant, tant que personne ne met à jour manuellement son catalog-info.yaml.

Pourquoi cette dérive arrive presque toujours

L’adoption initiale de Backstage génère typiquement un catalogue à jour, chaque équipe remplissant son catalog-info.yaml au moment du déploiement de la plateforme. Le problème survient ensuite : sans processus explicite (une vérification en CI, une revue périodique), la mise à jour du catalogue reste une tâche facultative que personne ne priorise face à des urgences de production. C’est exactement le problème que la réconciliation continue résout côté infrastructure (un contrôleur vérifie en permanence que l’état réel correspond à l’état déclaré) : Backstage, lui, ne réconcilie rien automatiquement, le catalogue restant figé sur ce qui a été écrit une fois dans catalog-info.yaml.

Le correctif : traiter le catalogue comme du code vérifié en CI

La pratique qui limite réellement cette dérive consiste à valider catalog-info.yaml en CI au même titre que n’importe quel autre fichier de configuration (schéma respecté, owner correspondant à une équipe existante), et à faire échouer une PR qui introduit un service sans entrée catalogue correspondante, plutôt que de compter sur la bonne volonté des équipes pour maintenir le catalogue à jour après coup.

À retenir

Backstage centralise la découverte des services à partir d’un fichier déclaratif (catalog-info.yaml), pas d’une observation en temps réel de l’infrastructure : sa valeur dépend entièrement de la fraîcheur de ce fichier, jamais garantie par l’outil lui-même. Sans processus explicite de vérification, le catalogue dérive silencieusement de la réalité, un piège d’adoption plus fréquent que n’importe quel problème technique de Backstage. Valider le catalogue en CI, exactement comme n’importe quelle autre configuration versionnée, est la seule pratique qui empêche réellement cette dérive de s’installer.