04 - Backstage.io: Platform Portal per Developer Self-Service e Service Catalog

Backstage: Il Developer Portal Open Source di Spotify

Backstage e una piattaforma open source creata da Spotify e donata alla Cloud Native Computing Foundation (CNCF) nel 2020. Rappresenta oggi lo standard de facto per la costruzione di developer portal e la base su cui molte organizzazioni costruiscono la propria Internal Developer Platform (IDP).

Backstage risolve un problema che ogni organizzazione in crescita affronta: la frammentazione degli strumenti e delle informazioni. Invece di navigare tra decine di dashboard, wiki, repository e tool, gli sviluppatori trovano tutto in un unico portale: il catalogo dei servizi, la documentazione, i template per nuovi progetti, lo stato dei deployment e le metriche di performance.

In questo articolo esploreremo l'architettura di Backstage, i suoi componenti core, come configurarlo e personalizzarlo, e come costruire plugin custom per integrarlo con il vostro ecosistema.

Architettura di Backstage

Backstage ha un'architettura modulare basata su tre componenti principali:

• Frontend (App): single-page application React che fornisce l'interfaccia utente. E altamente personalizzabile attraverso temi, layout e plugin frontend
• Backend: server Node.js/Express che gestisce le API, l'autenticazione, il database e l'orchestrazione dei plugin backend
• Plugins: moduli indipendenti che aggiungono funzionalità. Ogni plugin ha un componente frontend e/o backend. L'ecosistema conta centinaia di plugin per integrare tool come GitHub, Kubernetes, PagerDuty, Datadog e molti altri

Questa architettura a plugin e la vera forza di Backstage: permette di iniziare con le funzionalità core e aggiungere integrazioni progressivamente, senza mai dover riscrivere la piattaforma.

# Backstage: configurazione app-config.yaml
app:
  title: "Company Developer Portal"
  baseUrl: https://backstage.company.io

organization:
  name: "Company Inc."

backend:
  baseUrl: https://backstage.company.io
  listen:
    port: 7007
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location, Template, Group, User]
  locations:
    - type: url
      target: https://github.com/company/backstage-catalog/blob/main/all-components.yaml
    - type: url
      target: https://github.com/company/software-templates/blob/main/all-templates.yaml
      

Software Catalog: Il Cuore di Backstage

Il Software Catalog e il componente centrale di Backstage. E un registro centralizzato di tutti i componenti software dell'organizzazione: servizi, librerie, API, risorse infrastrutturali, documentazione e team. Ogni entità nel catalogo e descritta da un file YAML chiamato catalog-info.yaml che risiede nella root del repository del componente.

Il catalogo supporta diversi tipi di entità:

• Component: un servizio, una libreria o un'applicazione
• API: un'interfaccia esposta da un componente (REST, gRPC, GraphQL, eventi)
• System: un raggruppamento logico di componenti che formano un sistema
• Resource: una risorsa infrastrutturale (database, bucket S3, cluster Kafka)
• Group: un team o un'unita organizzativa
• User: un utente individuale dell'organizzazione

# catalog-info.yaml: definizione di un servizio nel catalogo
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout-service
  description: "Servizio per la gestione del checkout e pagamenti"
  annotations:
    github.com/project-slug: company/checkout-service
    backstage.io/techdocs-ref: dir:.
    pagerduty.com/service-id: PXXXXXX
    grafana/dashboard-selector: "checkout"
    sonarqube.org/project-key: checkout-service
  tags:
    - typescript
    - nestjs
    - payments
  links:
    - url: https://checkout.company.io/api/docs
      title: API Documentation
      icon: docs
    - url: https://grafana.company.io/d/checkout
      title: Grafana Dashboard
      icon: dashboard
spec:
  type: service
  lifecycle: production
  owner: team-checkout
  system: e-commerce
  providesApis:
    - checkout-api
  consumesApis:
    - payment-gateway-api
    - inventory-api
  dependsOn:
    - resource:checkout-database
    - resource:checkout-redis
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: checkout-api
  description: "REST API per operazioni di checkout"
spec:
  type: openapi
  lifecycle: production
  owner: team-checkout
  system: e-commerce
  definition:
    $text: ./openapi.yaml
      

Software Templates: Scaffolding dal Portale

I Software Templates sono il motore di scaffolding di Backstage. Permettono agli sviluppatori di creare nuovi servizi, librerie o componenti infrastrutturali direttamente dal developer portal, seguendo i Golden Paths dell'organizzazione.

Il flusso tipico e:

• Lo sviluppatore seleziona un template dal catalogo (es. "REST API Microservice")
• Compila un form con le informazioni richieste (nome, team owner, opzioni tecniche)
• Backstage esegue una serie di step automatizzati: scaffolding del codice, creazione repository GitHub, setup CI/CD, registrazione nel catalogo
• In pochi minuti, lo sviluppatore ha un servizio funzionante con tutte le best practice integrate

TechDocs: Documentazione nel Portale

TechDocs e il sistema di documentazione integrato in Backstage che implementa il paradigma docs-as-code. La documentazione vive nel repository del servizio come file Markdown, viene compilata automaticamente e resa accessibile dal developer portal.

I vantaggi di TechDocs sono:

• Co-location: la documentazione vive accanto al codice, quindi viene aggiornata insieme ad esso
• Discoverability: tutta la documentazione e ricercabile da un unico punto nel portale
• Standardizzazione: formato uniforme per tutta la documentazione dell'organizzazione
• Automazione: la compilazione e la pubblicazione sono automatiche tramite CI/CD

# mkdocs.yml: configurazione TechDocs per un servizio
site_name: Checkout Service
site_description: "Documentazione tecnica del servizio checkout"

nav:
  - Home: index.md
  - Architecture:
    - Overview: architecture/overview.md
    - Database Schema: architecture/database.md
    - API Design: architecture/api-design.md
  - Development:
    - Getting Started: development/getting-started.md
    - Local Setup: development/local-setup.md
    - Testing: development/testing.md
  - Operations:
    - Deployment: operations/deployment.md
    - Monitoring: operations/monitoring.md
    - Runbook: operations/runbook.md
  - ADR:
    - 001 - Database Choice: adr/001-database-choice.md
    - 002 - Cache Strategy: adr/002-cache-strategy.md

plugins:
  - techdocs-core

markdown_extensions:
  - admonition
  - codehilite
  - pymdownx.superfences
  - pymdownx.tabbed
      

Plugin Development

La vera potenza di Backstage risiede nel suo ecosistema di plugin. Oltre ai centinaia di plugin della community, ogni organizzazione può creare plugin custom per integrare i propri tool interni, dashboard e workflow.

Un plugin Backstage tipicamente comprende:

• Frontend plugin: componenti React che aggiungono pagine, card o tab nell'interfaccia
• Backend plugin: API e logica server-side che il frontend consuma
• Common package: tipi TypeScript, interfacce e utilities condivise tra frontend e backend

I plugin più diffusi nell'ecosistema includono: Kubernetes (visualizzazione pods e deployment), GitHub Actions (stato dei workflow), PagerDuty (on-call e incidenti), Grafana (dashboard embedded), SonarQube (code quality), e Cost Insights (analisi costi cloud).

Deployment di Backstage

Backstage può essere deployato in diversi modi, a seconda delle esigenze dell'organizzazione:

• Kubernetes: il metodo consigliato per produzione, con Helm chart o manifest custom
• Docker Compose: ideale per sviluppo locale e piccoli team
• Roadie: versione SaaS managed di Backstage, per chi non vuole gestire l'infrastruttura

# Kubernetes deployment: Helm values per Backstage
backstage:
  image:
    registry: ghcr.io
    repository: company/backstage
    tag: latest

  replicas: 2

  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 1Gi

  extraEnvVars:
    - name: POSTGRES_HOST
      valueFrom:
        secretKeyRef:
          name: backstage-db-credentials
          key: host
    - name: GITHUB_TOKEN
      valueFrom:
        secretKeyRef:
          name: backstage-github-token
          key: token

  ingress:
    enabled: true
    host: backstage.company.io
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod
    tls:
      - secretName: backstage-tls
        hosts:
          - backstage.company.io

postgresql:
  enabled: true
  auth:
    database: backstage
    username: backstage
  primary:
    persistence:
      size: 10Gi