TP27 : Platform Engineering : portail développeur Backstage et Golden Path

Après une vingtaine de TP, la chaîne est complète mais complexe : un développeur qui veut créer un nouveau service doit connaître Docker, la CI, les scanners, Kubernetes, GitOps et l’observabilité. Le Platform Engineering répond à cette charge cognitive en construisant une Internal Developer Platform (IDP) : un produit interne qui offre des chemins recommandés (Golden Paths) en libre-service. Backstage, créé par Spotify et incubé à la CNCF, en est le portail le plus répandu : catalogue des logiciels et de leurs propriétaires, documentation au plus près du code, et Software Templates qui génèrent un service déjà conforme.

Fichiers de départ : app-config.local.yaml.example, catalog.zip, templates.zip

1. Objectifs pédagogiques

À l’issue du TP, vous serez capable de :

• expliquer les notions de plateforme comme produit, d’IDP, de Golden Path et de charge cognitive ;
• créer et lancer une application Backstage ;
• modéliser un système dans le catalogue (Component, API, System, Resource, Group, User) ;
• publier une documentation TechDocs à partir du dépôt ;
• écrire un Software Template qui crée un dépôt GitHub conforme et l’enregistre dans le catalogue ;
• situer chaque outil des TP précédents dans une architecture Infrastructure → Platform → Applications.

Les images de cette page sont des schémas explicatifs, pas des captures d’écran.

2. Environnement du TP

• VM de lab Ubuntu Server 26.04 avec ≥ 4 Go de RAM libres et Node.js en version LTS supportée par Backstage (vérifier la page Getting Started ; Node 24 si supporté), yarn via Corepack, git, python3-pip :

  corepack enable
  node --version && yarn --version
  pip install --user mkdocs-techdocs-core      # pour générer TechDocs en local

• Un compte GitHub et un personal access token (scope repo, ou fine-grained avec création de dépôts) exporté dans GITHUB_TOKEN.

• Le dépôt contact-api du TP8 sur GitHub.

3. Partie 1 : Créer et lancer Backstage

• Créer l’application à la racine du dépôt des TP (les chemins du fichier de configuration fourni en dépendent), puis la lancer :

  cd <dépôt-des-TP>
  npx @backstage/create-app@latest      # nom : backstage
  cd backstage
  cp ../partie-9-platform-engineering/tp27-backstage/app-config.local.yaml.example app-config.local.yaml
  export GITHUB_TOKEN=<token>
  yarn start                            # front : http://localhost:3000, back : 7007

  Depuis une autre machine : tunnel SSH ssh -L 3000:localhost:3000 -L 7007:localhost:7007 <vm>.

• Se connecter en Guest et parcourir les entités d’exemple. Où sont-elles déclarées (app-config.yaml, examples/) ?

4. Partie 2 : Catalogue

• Vérifier que l’organisation de catalog/org.yaml est chargée (Catalog → Kind: Group). Ajouter un utilisateur à votre nom.
• Copier catalog/contact-api.yaml sous le nom catalog-info.yaml à la racine du dépôt contact-api, remplacer TODO-utilisateur, compléter la Resource contact-db et la dépendance, puis pousser.
• Enregistrer ce fichier : Create → Register Existing Component avec l’URL du catalog-info.yaml (ou en l’ajoutant aux locations de app-config.local.yaml).
• Explorer la fiche contact-api : propriétaire, système, graphe des relations, onglet API (la définition OpenAPI est rendue et testable).
• Enregistrer de la même façon le dépôt GitOps du TP19 comme Component de type website ou service.

5. Partie 3 : TechDocs

• Dans contact-api, ajouter mkdocs.yml et docs/index.md (installation, routes, exploitation), pousser, puis ouvrir l’onglet Docs de la fiche.
• Expliquer l’intérêt d’une documentation versionnée avec le code (« docs as code ») par rapport à un wiki séparé.

6. Partie 4 : Software Template et Golden Path

• Étudier templates/node-service/template.yaml et son skeleton/ :
  • paramètres du formulaire ;
  • étapes fetch:template, publish:github, catalog:register ;
  • fichiers générés : Dockerfile multi-stage non-root (TP7), CI avec Gitleaks et Trivy (TP10), Deployment conforme aux policies (TP17), fiche catalogue, TechDocs.
• Compléter le paramètre port et l’utiliser dans le squelette (Dockerfile, server.js, Deployment).
• Create → Service Node.js (Golden Path) → créer orders-api. Vérifier :
  • le nouveau dépôt GitHub et son contenu ;
  • le premier run de la CI ;
  • la fiche orders-api dans le catalogue, avec son owner et sa documentation.
• Ajouter au template une étape de votre choix (par exemple l’ajout du service dans le dépôt GitOps via publish:github:pull-request) ou rédiger précisément comment vous le feriez.
• Définir en quelques lignes le Golden Path de votre organisation : ce qui est fourni, ce qui est imposé, ce qui reste libre. Pourquoi un Golden Path doit-il être le chemin le plus simple, pas seulement le chemin obligatoire ?

7. Partie 5 : Architecture en trois couches

• Placer chaque outil utilisé depuis le TP1 dans l’une des trois couches, sous forme de schéma :

Applications   : contact-api, portfolio, orders-api…
      ↑  Golden Paths, API de plateforme (Backstage, Crossplane, kro)
Platform       : CI/CD, registre, GitOps, observabilité, sécurité, secrets…
      ↑
Infrastructure : VM, Vagrant, Terraform / OpenTofu, Ansible, K3s, Floci…

• Pour chaque couche, indiquer qui en est responsable et quelle interface elle offre à la couche du dessus.

Défi

1. Installer le plugin Kubernetes de Backstage et afficher les Pods de contact-api dans sa fiche (annotation backstage.io/kubernetes-id, configuration du cluster K3s dans app-config.local.yaml).
2. Remplacer l’authentification Guest par une authentification OIDC avec le Keycloak du TP16.

8. Livrables

Captures à déposer dans captures/ :

Ainsi que le template complété, les catalog-info.yaml, le texte du Golden Path et le schéma en trois couches. Jamais le GITHUB_TOKEN.