À la fin de ce tutoriel, vous poserez un Internal Developer Portal avec Backstage : enregistrer des services via catalog-info.yaml, scaffolder un micro-service avec un Software Template, publier de la doc TechDocs, et relier le catalogue à GitOps / Kubernetes — en lab local, sans publish prod.

Niveau : Intermédiaire · Temps estimé : 60–75 min · Versions cibles : Backstage (@backstage/create-app 2026), Node.js 20 LTS, Yarn (scaffold) · Dernière vérification : 2026-09-11

Slug proposé : wow-backstage-idp · Série : Platform Engineering / DevOps · Mot-clé SEO : backstage idp · Nouveau — page WOW Platform

Statut : HOLD — draft only (ne pas publier sur WordPress)

Prérequis

  • Git + YAML ; terminal Linux/macOS (ou WSL2) ; Node.js 20+
  • K8s lab optionnel : kubeadm, Helm
  • GitOps day-2 : Argo CD · conteneurs : Docker containers
  • ~4 Go RAM libre pour frontend + backend Backstage

Objectif : instance locale (auth Guest), une Component cataloguée, un template qui génère un squelette + catalog-info.yaml, TechDocs OK, check-list ownership / plugins.

Ce que nous allons construire

Lab IDP Backstage (WOW)
  ├── create-app → app Node (frontend + backend)
  ├── Auth Guest (lab)
  ├── catalog-info.yaml : System + Component + API
  ├── Software Template (scaffolder)
  ├── TechDocs (mkdocs)
  ├── Plugins Catalog / Scaffolder / TechDocs (+ K8s lecture)
  ├── Lien GitOps (Argo CD / CI)
  └── Day-2 : ownership, scorecards, RBAC, upgrades

(Schéma — alt : « Backstage IDP : catalogue, templates, TechDocs et plugins vers GitOps/Kubernetes ».)

Étape 1 — Pourquoi un IDP, et pourquoi Backstage ?

Une IDP réduit le ticket hell : self-service pour créer un service, voir l’owner, la doc, et les standards (CI, sécu, obs).

Terme Rôle
Portal UI unique (Backstage)
Catalogue Inventaire Git des Software Entities
Platform Paved roads : templates, pipelines, policies
IDP Portal + catalogue + paved roads + gouvernance

Backstage (Spotify → CNCF) est le standard open source du developer portal en 2026. Il ne remplace ni Kubernetes, ni Argo CD, ni Terraform : c’est le point d’entrée développeur. Sans catalog-info.yaml et ownership réels, le portal reste un tableau vide.

Angle DEH : catalogue Git-backed, templates qui encodent Dockerfile / CI OIDC / probes, plugins qui branchent l’existant plutôt que de tout réécrire.

Trois anti-patterns fréquents : (1) importer 500 repos sans owner — le catalogue devient du bruit ; (2) un template « fourre-tout » de 40 paramètres — personne ne le lance ; (3) brancher dix plugins avant d’avoir dix catalog-info.yaml propres. Inversez l’ordre : données catalogue d’abord, un gold path, puis les intégrations runtime.

Étape 2 — Architecture mentale

Brique Rôle lab
App Frontend React + backend Node
Software Catalog Ingest YAML (Component, System, API, Template, Location…)
Software Templates Scaffolder = paved road
TechDocs Docs-as-code (MkDocs) dans le portal
Plugins Cartes UI + APIs (K8s, CI, scorecards)
Auth Guest en lab ; org = GitHub/GitLab/Microsoft + policies

Fichier clé : catalog-info.yaml à la racine du dépôt, lu via une Location (Git ou fichier local).

Étape 3 — Scaffold lab

node -v   # 20+
npx @backstage/create-app@latest
# Nom suggéré : deh-backstage-lab
cd deh-backstage-lab
yarn install
yarn start   # ports typiques 3000 / 7007

UI : http://localhost:3000. Gardez Guest en lab. Aucun secret OAuth/token dans Git — env + .gitignore.

curl -sS -o /dev/null -w "%{http_code}n" http://localhost:7007/api/catalog/entities || true

Boot KO : Node trop vieux, registry bloqué, ou ports pris — corrigez l’env avant les plugins.

En lab mono-machine, évitez de lancer en parallèle un gros kube-prometheus-stack : Backstage + cluster monitoring saturent vite 8 Go. Gardez le portal seul pour la première heure, puis ajoutez le plugin K8s quand le catalogue est stable.

Étape 4 — catalog-info.yaml

Dépôt lab payments-api :

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: payments
  description: Domaine paiements — lab DEH
spec:
  owner: group:default/platform
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments-api
  description: API paiements (lab)
  tags: [nodejs, api, lab]
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: experimental
  owner: group:default/platform
  system: payments
  providesApis: [payments-api]
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: payments-api
  description: OpenAPI stub lab
spec:
  type: openapi
  lifecycle: experimental
  owner: group:default/platform
  system: payments
  definition: |
    openapi: "3.0.0"
    info: { title: payments-api, version: 0.1.0 }
    paths: {}

UI : Create → Register existing component → Location locale ou URL Git raw. Attendu : System, Component, API, owner visibles.

Règles : owner réel (group: / user:), lifecycle honnête, tags utiles, une Component = un déploiement logique.

Étape 5 — Software Template minimal

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: deh-service-nodejs
  title: Service Node.js DEH
  description: Squelette + catalog-info + Dockerfile
spec:
  owner: group:default/platform
  type: service
  parameters:
    - title: Service
      required: [name, description, owner]
      properties:
        name:
          type: string
          pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
        description: { type: string }
        owner: { type: string, default: group:default/platform }
  steps:
    - id: fetch
      name: Fetch skeleton
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
    - id: log
      name: Sortie lab
      action: debug:log
      input:
        message: Généré ${{ parameters.name }} — publiez sur Git
  output:
    links:
      - title: Catalogue
        url: /catalog

Le dossier skeleton/ : catalog-info.yaml (templated), README.md, Dockerfile, stub app. En org : étape publish:github / publish:gitlab + enregistrement Location. Lancez via Create → template → vérifiez la Component après push Git.

Étape 6 — TechDocs

# mkdocs.yml
site_name: payments-api
nav:
  - Accueil: index.md
  - Runbook: runbook.md

# docs/index.md
# payments-api
Service lab DEH. Owner : platform.

Annotation backstage.io/techdocs-ref: dir:.. En prod, buildez TechDocs en CI (artefacts S3 ca-central-1 / GCS) plutôt que dans le pod portal. Onglet Docs : si 404 → mkdocs.yml / docs/ absents ou générateur non configuré.

Étape 7 — Plugins et GitOps

  1. Catalog + Scaffolder + TechDocs (cœur)
  2. Plugin Kubernetes lecture (backstage.io/kubernetes-id / labels) sur cluster lab
  3. Discovery GitHub/GitLab pour importer les catalog-info.yaml
  4. Lien CI : GitHub Actions OIDC AWS
  5. GitOps : la Component pointe vers l’Application Argo CD — Argo CD reste la source de vérité cluster

Backstage décrit ; Argo / Terraform / pipelines mutent. Ne transformez pas le portal en second CD opaque.

Exemple de boucle saine : template crée le repo + catalog-info → CI (OIDC) build/push → Argo CD sync le path GitOps → plugin K8s dans Backstage montre le Deployment healthy. Chaque outil garde un rôle clair ; le développeur ne voit qu’un fil dans le portal.

Étape 8 — Day-2

  • Ownership aligné IdP ; service sans owner = alerte
  • Scorecards : 5 checks max au début (runbook, scan image, probes, pipeline OIDC…)
  • RBAC : Guest = lab only ; permission framework en org
  • Secrets : env / secret manager — jamais dans app-config.yaml Git
  • Upgrades : pin plugins, notes de version Backstage, CI image portal
  • Obs portal : uptime backend — portal down = self-service down
  • Mesure d’adoption : nombre de Components avec owner réel, templates exécutés / mois, % services avec TechDocs runbook. Sans métriques, l’IDP reste un slide PowerPoint.

Troubleshooting

Symptôme Correctif
Entity absente Location / YAML / kind invalide
Owner missing Créer Group/User ou aligner IdP
Template KO Action scaffolder ou URL fetch:template
TechDocs 404 mkdocs.yml, docs/, annotation
Plugin K8s vide Annotation ≠ sélecteur ; kubeconfig backend
OOM / boot lent Moins de plugins ; 4 Go+ RAM
Guest en « prod » IdP + RBAC avant ouverture équipe

FAQ

Backstage remplace-t-il ServiceNow / Jira ?
Non. Il coupe une partie du provisioning via templates ; l’ITSM reste ailleurs.

Un catalog-info.yaml par micro-service ?
Oui : une Component (et APIs) par service déployable ; les Systems regroupent le domaine.

Sans Git ?
Lab local OK ; en équipe, Git + discovery est le minimum (audit, PR).

Vs un portal Markdown ?
Le Markdown ne scale pas sur ownership, templates et plugins live. Backstage coûte plus cher à opérer : gardez-le quand catalogue + self-service sont de vrais problèmes.

Par où commencer en entreprise ?
10 services pilotes + owners → un template gold path → TechDocs runbook → un plugin runtime (K8s ou CI) → scorecards légères.

Quiz (5 questions)

1. Fichier d’entrée catalogue d’un service : – A. docker-compose.yml · B. catalog-info.yaml · C. skaffold.yaml

2. Un Software Template sert à : – A. Remplacer Argo CD · B. Générer un service conforme (scaffolder) · C. Stocker les secrets prod dans Git

3. TechDocs, c’est : – A. Un CDN obligatoire · B. Docs-as-code (souvent MkDocs) dans le portal · C. Un équivalent Prometheus

4. En ouverture équipe, après le lab Guest, il faut surtout : – A. Garder Guest · B. Brancher IdP + RBAC · C. Désactiver le catalogue

5. Backstage vs Argo CD : – A. Remplace GitOps · B. Portal/catalogue ; GitOps reste la vérité déploiement · C. Écrit les manifests à la place de Git

Réponses : 1‑B · 2‑B · 3‑B · 4‑B · 5‑B

Pour aller plus loin

Maillage Platform Engineering / DevOps
Hub voisin Argo CD · Helm · Docker containers
CI / Cloud GitHub Actions OIDC AWS
Obs Prometheus Grafana Kubernetes Helm
Synthèse Capstone Project

Meta publication (SEO) — Publish: HOLD

  • Title SEO : Backstage IDP : catalogue de services, templates et TechDocs (2026)
  • Meta description : Backstage comme Internal Developer Portal : catalog-info, Software Templates, TechDocs, plugins K8s/GitOps. Lab create-app FR 2026 (HOLD).
  • Focus keyword : backstage idp
  • Schemas : Article + HowTo + FAQ
  • Image mise en avant : assets/web/devopelastichayway/cover-wow-backstage-idp-1200x630.webp (alt : Backstage IDP — catalogue services et portal développeur)
  • Catégorie : Platform Engineering / DevOps · Niveau : Intermédiaire
  • Slug / URL : wow-backstage-idp → /tutoriels/wow-backstage-idp/
  • Statut : brouillon local — ne pas publier tant que feu vert Maître / SEO

← Catalogue Tutoriels

Pour aller plus loin — hubs live

Retour parcours Catalogue Tutoriels — hub de la série et leçons sœurs.

© 2023 devopelastichayway.com All rights reserved.