Backstage[1], open-sourced por Spotify en 2020, es la base más usada para construir Internal Developer Platforms (IDPs). Se ha consolidado como la referencia del sector, adoptado por Spotify, American Airlines, Netflix, Roku y centenares de organizaciones más. No es un producto cerrado: es una plataforma extensible que cada organización adapta. Cubrimos cómo funciona, qué obtienes de serie, y los costes de adopción que rara vez se mencionan en los talks de conferencia.

Puntos clave

  • Backstage es una aplicación web Node.js + React que actúa como portal único para servicios, docs, scaffolding y búsqueda.

  • El software catalog es el núcleo: cada entidad se describe en YAML y las relaciones se infieren automáticamente.

  • El scaffolder convierte la promesa de "golden paths" en realidad, pero cada template es código que hay que mantener.

  • Para organizaciones con menos de 30-50 desarrolladores, la inversión rara vez se recupera.

  • Adoptarlo bien requiere 1-3 ingenieros dedicados durante meses, no un proyecto de fin de semana.

Qué es realmente

Backstage es una aplicación web (Node.js + React) que actúa como portal único para todo lo que un desarrollador necesita en su trabajo. Cinco bloques principales:

  • Catálogo de servicios: inventario centralizado de qué existe, quién lo mantiene y sus dependencias.

  • Plugins: cada función adicional (estado de CI/CD, Kubernetes, monitoring, docs, costes cloud) viene como plugin enchufable.

  • Scaffolder: generador de nuevos componentes a partir de plantillas estándar.

  • TechDocs: documentación como código, renderizada dentro del portal.

  • Search: búsqueda federada sobre todo lo anterior.

La visión es un solo sitio donde el desarrollador encuentra qué existe, cómo crear cosas nuevas, dónde está la documentación y qué está pasando con sus servicios.

Software Catalog: el corazón

Cada entidad en Backstage se describe con un YAML simple:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
  description: Servicio que gestiona órdenes de compra
spec:
  type: service
  lifecycle: production
  owner: team-orders
  system: ecommerce

Tipos principales de entidad: Component (servicios, librerías, websites), API, Resource (DBs, queues), System (agrupaciones), Group (equipos), User, Domain (áreas funcionales).

Las relaciones se infieren del YAML: "este componente pertenece al sistema X, su API la consume Y, está en el dominio Z". Backstage construye una red navegable de toda la arquitectura. El catálogo se alimenta de tres fuentes:

  • Locations (URLs de YAMLs): pueden vivir en el repo de cada servicio o estar centralizados.

  • Providers que descubren entidades automáticamente (cluster de Kubernetes, GitHub orgs, etc.).

  • Manualmente vía interfaz web.

Plugins: dónde está el ecosistema

Backstage solo es útil con plugins. Los más importantes en la práctica:

  • GitHub / GitLab: ver repo, PRs y contributors directamente en el portal.

  • CI/CD: estado de builds, despliegues y ejecuciones (Tekton, ArgoCD, Jenkins, GitHub Actions).

  • Kubernetes: ver pods, despliegues y eventos del componente actual.

  • TechDocs: documentación markdown dentro del portal.

  • PagerDuty / Opsgenie: oncall actual de cada servicio.

  • Datadog / Grafana / NewRelic: dashboards embebidos del componente.

  • Cost Insights: coste cloud por servicio.

Hay 100+ plugins oficiales y de comunidad. Construir el tuyo propio es un ejercicio de React más un par de archivos de configuración.

El Scaffolder: golden paths en acción

El scaffolder es donde Backstage convierte la promesa de platform engineering en realidad. Defines templates que generan de golpe:

  • Repositorio nuevo en GitHub con estructura estándar.

  • Pipeline de CI configurado.

  • Manifests de Kubernetes con resource limits y health checks.

  • Dashboard de Grafana pre-creado.

  • Alertas básicas.

  • Entrada en el catálogo apuntando al nuevo componente.

Todo desde un wizard web donde el desarrollador rellena pocos campos (nombre, equipo, tipo). Lo que tomaría horas o días manualmente, se hace en minutos.

Implementarlo requiere inversión real: cada template es código (YAML + shell + actions de Backstage), y mantenerlo cuando las convenciones internas cambian es trabajo continuo; no es un proyecto puntual.

TechDocs: docs como código

TechDocs renderiza markdown del repo del propio servicio dentro del portal. La documentación vive con el código, se actualiza en los mismos PRs y se ve con buena UX en un sitio centralizado.

Internamente usa MkDocs como motor de renderizado. La integración: añade un mkdocs.yml y una carpeta docs/ al repo, refléjalo en el catalog-info.yaml, y aparece en Backstage. Es una de las features más adoptadas porque resuelve un problema real: documentación dispersa entre Confluence, wikis, READMEs y PDFs.

El coste real de adoptar Backstage

Los talks de conferencia venden Backstage como "instalar y listo". La realidad de implantarlo en serio tiene cinco componentes de coste:

  • Equipo dedicado. Adoptarlo bien requiere 1-3 ingenieros full-time durante meses para configuración, plugins y migración.

  • Inversión continua. Plugins evolucionan, integraciones cambian, templates necesitan mantenimiento. No es un "proyecto": es un producto interno.

  • Curva de aprendizaje React/Node.js. Si tu equipo es backend-heavy, adoptar el frontend de Backstage es una habilidad nueva.

  • Datos en buen estado. Si tu inventario actual es un Excel desactualizado, Backstage no lo arreglará; solo lo expondrá.

  • Adopción cultural. Los desarrolladores tienen que ir al portal, mantener su catalog-info, escribir TechDocs. Sin impulso organizativo, queda infrautilizado.

Para organizaciones con menos de 30-50 desarrolladores, la inversión rara vez compensa. Para organizaciones más grandes, el ROI puede ser sustancial, pero requiere compromiso real, no un proyecto de viernes.

Alternativas y opciones gestionadas

Backstage no es la única opción:

  • Port[2]: SaaS managed con catálogo y portal, menor flexibilidad pero cero operación.

  • Cortex[3]: similar, foco en service catalog y scorecards de madurez.

  • Roadie y Spotify Portal for Backstage: versión managed de Backstage por empresas externas.

  • Construcción casera: para organizaciones con stack específico, a veces un dashboard custom sale mejor.

Conclusión

Backstage es la elección por defecto si tu organización tiene escala y compromiso para construir un IDP serio. Su flexibilidad es su fortaleza y su exigencia: te obliga a tomar decisiones que otras herramientas más opinionadas resuelven por ti. Si aciertas con la inversión y el respaldo organizativo, el resultado es valioso. Si lo abordas como "instalar Backstage los viernes", quedará a medio camino.

Preguntas frecuentes

¿Compensa adoptar Backstage en una empresa pequeña?

Rara vez: para organizaciones con menos de 30-50 desarrolladores la inversión casi nunca se recupera. Adoptarlo bien exige 1-3 ingenieros dedicados durante meses para configuración, plugins y migración, y después mantenimiento continuo de templates e integraciones. Si tu inventario actual es un Excel desactualizado, Backstage no lo arregla, solo lo expone. Alternativas gestionadas como Port, Cortex o Roadie eliminan la operación a cambio de menos flexibilidad.

¿Cómo se alimenta el catálogo de servicios de Backstage?

Desde tres fuentes: las locations son URLs de ficheros YAML que pueden vivir en el repo de cada servicio o centralizados. Los providers descubren entidades automáticamente, como un cluster de Kubernetes o una organización de GitHub. La tercera vía es el alta manual desde la interfaz web. Cada entidad se describe en YAML con kind, metadata y spec (type, lifecycle, owner, system), y Backstage infiere las relaciones entre componentes, APIs, sistemas y dominios.

¿Qué necesito para que la documentación de un servicio aparezca en TechDocs?

Añadir un mkdocs.yml y una carpeta docs/ con markdown al repo del propio servicio y reflejarlo en su catalog-info.yaml; a partir de ahí aparece renderizada dentro del portal. TechDocs usa MkDocs como motor y la documentación vive con el código, se actualiza en los mismos PRs y sustituye la dispersión entre Confluence, wikis, READMEs y PDFs.

Fuentes

  1. Backstage
  2. Port
  3. Cortex
  4. CNCF: Backstage project
  5. Repositorio GitHub