Paul Escarcena
Blog
Paul Escarcena

Contenido

Backstage Series #1: Primeros pasos con Backstage

Paul Escarcena incluido en Backstage Series
   1670 palabras   8 minutos   ... vistas  
/images/backstage-series/backstage-header.png

Actualización (Marzo 2026): Este artículo fue actualizado para reflejar los cambios más recientes en Backstage. Se actualizaron los requisitos de Node.js (ahora v22+), la versión de Yarn (ahora v4.4.1 via Corepack), el comando de inicio (yarn start en lugar de yarn dev) y el bundler (Rspack en lugar de Webpack).

¿Qué es Backstage?

Imagínate que estás en una empresa donde hay decenas (o cientos) de microservicios, pipelines de CI/CD, documentación regada por todos lados, y cada equipo usa herramientas diferentes. Un caos, ¿verdad? Bueno, ahí es donde entra Backstage.

Backstage es una plataforma open source creada por Spotify que funciona como un portal unificado para desarrolladores. Piensa en él como un “hub” centralizado donde puedes:

  • Catalogar todos tus servicios, APIs y recursos en un solo lugar.
  • Crear nuevos proyectos a partir de templates estandarizados (adiós a copiar y pegar repos).
  • Visualizar documentación técnica sin salir de la plataforma.
  • Integrar herramientas como Kubernetes, GitHub, CI/CD, monitoreo y mucho más a través de plugins.

En resumen, Backstage te ayuda a poner orden en el caos y le da a tu equipo una experiencia unificada para gestionar toda la infraestructura y los servicios.

¿Para qué sirve realmente?

Te lo pongo así de simple: si alguna vez te has preguntado "¿quién es dueño de este servicio?", "¿dónde está la documentación de esta API?" o "¿cómo creo un nuevo microservicio siguiendo los estándares del equipo?", entonces Backstage es para ti.

Sus principales capacidades son:

  1. Software Catalog: Un inventario de todo lo que tu organización tiene — servicios, APIs, librerías, pipelines, etc.
  2. Software Templates: Plantillas para crear nuevos proyectos de forma estandarizada. Defines el template una vez y cualquier dev puede usarlo.
  3. TechDocs: Documentación técnica que vive junto al código y se renderiza automáticamente en Backstage.
  4. Plugins: Un ecosistema enorme de plugins que extienden la funcionalidad — desde Kubernetes hasta PagerDuty.

Instalación en local

Vamos a lo bueno. Para instalar Backstage en tu máquina, necesitas tener instalado:

  • Node.js (versión 22 o 24 — Active LTS)
  • Yarn (versión 4.4.1 — se instala via Corepack)
  • Git
  • Docker (opcional, pero recomendado para la base de datos)
  • Build tools (make y build-essential en Linux, o xcode-select --install en macOS)

Si usas nvm, puedes instalar la versión correcta de Node así:

nvm install 22

Y para habilitar Yarn 4 via Corepack:

corepack enable

¿Usas Windows? Backstage está diseñado para entornos Unix (Linux/macOS), pero puedes usarlo en Windows con WSL2 (Windows Subsystem for Linux). Aquí te dejo cómo preparar tu entorno:

  1. Instalar WSL2 — Abre PowerShell como administrador y ejecuta:

    wsl --install

    Esto instala Ubuntu por defecto. Reinicia tu máquina cuando termine.

  2. Entrar a WSL — Abre una terminal y escribe wsl o busca “Ubuntu” en el menú de inicio.

  3. Instalar dependencias dentro de WSL:

    sudo apt update && sudo apt install -y build-essential curl git

  4. Instalar Node.js con nvm (dentro de WSL):

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
corepack enable

A partir de aquí, todos los comandos de instalación de Backstage son los mismos. Solo asegúrate de ejecutarlos siempre dentro de WSL, no en PowerShell o CMD.

Paso 1: Crear la app de Backstage

Abre tu terminal y ejecuta:

npx @backstage/create-app@latest

Te va a preguntar el nombre de tu app. Ponle el nombre que quieras, por ejemplo mi-backstage:

? Enter a name for the app [required] mi-backstage

Esto va a crear una carpeta con toda la estructura del proyecto. Tómate un café mientras se instalan las dependencias, porque tarda un poquito.

Paso 2: Entrar al directorio

cd mi-backstage

Paso 3: Levantar Backstage en modo desarrollo

Ahora viene la parte emocionante. Para levantar Backstage localmente, solo ejecuta:

yarn start

Este comando levanta tanto el backend como el frontend en modo desarrollo. Después de unos segundos, deberías ver algo así en tu terminal:

[0] Rspack compiled successfully
[1] Listening on :7007

Abre tu navegador y ve a http://localhost:3000 y deberías ver la interfaz de Backstage funcionando.

Backstage corriendo en local

Backstage corriendo en local

¡Así de fácil! Ya tienes Backstage corriendo en tu máquina.

Integraciones: Kubernetes, GitHub y más

Ahora, donde Backstage realmente brilla es en sus integraciones. Te cuento las más interesantes:

Kubernetes

Con el plugin de Kubernetes, puedes ver el estado de tus deployments, pods, y services directamente desde Backstage. Imagina poder ver los logs de un pod o verificar si un deployment está healthy sin tener que abrir kubectl en la terminal. Todo desde una interfaz visual amigable.

GitHub

La integración con GitHub te permite:

  • Autenticación con GitHub OAuth.
  • Descubrir repositorios automáticamente y agregarlos al catálogo.
  • Disparar GitHub Actions desde los templates.
  • Ver pull requests y issues relacionados a un servicio.

Autenticación y autorización

Algo muy importante cuando hablamos de una plataforma como Backstage es cómo manejar quién accede y qué puede hacer. Y acá la buena noticia es que Backstage es bastante flexible. Soporta varios mecanismos de autenticación que probablemente ya estés usando en tu organización:

  • OAuth 2.0: Conecta con proveedores como GitHub, GitLab, Google, Microsoft, Okta, entre otros. Es la forma más común de autenticar usuarios.
  • OIDC (OpenID Connect): Si tu empresa usa un Identity Provider compatible con OIDC (como Keycloak, Auth0 o Azure AD), puedes integrarlo directamente. Esto te da Single Sign-On (SSO) sin mayor complicación.
  • Service Accounts (SA): Para integraciones máquina-a-máquina o procesos automatizados, puedes usar tokens de servicio. Muy útil cuando tienes pipelines de CI/CD que necesitan interactuar con la API de Backstage.
  • SAML 2.0: Si tu organización todavía usa SAML (bastante común en empresas grandes), Backstage también lo soporta.
  • Guest Access: Para entornos de desarrollo o demos, puedes habilitar acceso sin autenticación. Obviamente, no lo uses en producción.

Lo interesante es que puedes combinar varios proveedores. Por ejemplo, tener GitHub OAuth para los desarrolladores y OIDC con Keycloak para los equipos de operaciones. Backstage te deja configurar múltiples proveedores de autenticación al mismo tiempo.

Otras integraciones populares

  • ArgoCD: Visualiza el estado de tus deployments GitOps.
  • Jenkins / GitHub Actions: Monitorea tus pipelines de CI/CD.
  • PagerDuty: Ve quién está de guardia para cada servicio.
  • Grafana: Dashboards de monitoreo embebidos.
  • SonarQube: Métricas de calidad de código.

Ejemplo práctico: Template de Deployment en Kubernetes

Una de las funcionalidades más poderosas de Backstage son los Software Templates. Vamos a ver un ejemplo de cómo crear un template que genere un Deployment de Kubernetes. La idea es que cualquier desarrollador pueda crear un deployment solo llenando unos campos como el nombre de la app, el namespace, la cantidad de réplicas y la imagen.

¿Dónde colocar el template?

Los templates se definen en archivos YAML y generalmente se organizan así dentro de tu proyecto de Backstage:

mi-backstage/
├── templates/
│   └── kubernetes-deployment/
│       ├── template.yaml          # Definición del template
│       └── skeleton/
│           └── deployment.yaml    # El archivo que se va a generar

El archivo template.yaml es el que Backstage lee para saber qué parámetros pedir y qué acciones ejecutar. El directorio skeleton/ contiene los archivos que se van a generar con los valores que el usuario ingrese.

Registrar el template en Backstage

Para que Backstage reconozca tu template, necesitas agregarlo en el archivo app-config.yaml dentro de la sección catalog.locations. Simplemente añade una entrada apuntando a tu template.yaml:

catalog:
  locations:
    # ... otras locations que ya tengas ...

    # Kubernetes Deployment template
    - type: file
      target: ../../templates/kubernetes-deployment/template.yaml
      rules:
        - allow: [Template]

Con esto, cuando levantes Backstage y vayas a la sección “Create”, tu template va a aparecer listo para usarse.

El template YAML

Aquí tienes un ejemplo de template.yaml:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: kubernetes-deployment
  title: Kubernetes Deployment
  description: Crea un Deployment de Kubernetes con los parámetros básicos
  tags:
    - kubernetes
    - deployment
spec:
  owner: team-platform
  type: service

  parameters:
    - title: Configuración del Deployment
      required:
        - appName
        - namespace
        - replicas
        - image
      properties:
        appName:
          title: Nombre de la aplicación
          type: string
          description: El nombre de tu aplicación
          ui:autofocus: true
        namespace:
          title: Namespace
          type: string
          description: El namespace de Kubernetes donde se desplegará
          default: default
        replicas:
          title: Réplicas
          type: number
          description: Cantidad de réplicas del deployment
          default: 2
        image:
          title: Imagen Docker
          type: string
          description: "La imagen del contenedor (ej: mi-registro/mi-app:latest)"

  steps:
    - id: fetch-skeleton
      name: Generar archivos
      action: fetch:template
      input:
        url: ./skeleton
        values:
          appName: ${{ parameters.appName }}
          namespace: ${{ parameters.namespace }}
          replicas: ${{ parameters.replicas }}
          image: ${{ parameters.image }}

    - id: publish
      name: Publicar en GitHub
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        repoUrl: github.com?owner=tu-org&repo=${{ parameters.appName }}-deployment
        description: "Deployment de ${{ parameters.appName }}"

  output:
    links:
      - title: Repositorio
        url: ${{ steps.publish.output.remoteUrl }}

El skeleton del Deployment

Y este sería el archivo skeleton/deployment.yaml que se genera con los valores ingresados:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ${{ values.appName }}
  namespace: ${{ values.namespace }}
  labels:
    app: ${{ values.appName }}
spec:
  replicas: ${{ values.replicas }}
  selector:
    matchLabels:
      app: ${{ values.appName }}
  template:
    metadata:
      labels:
        app: ${{ values.appName }}
    spec:
      containers:
        - name: ${{ values.appName }}
          image: ${{ values.image }}
          ports:
            - containerPort: 8080
          resources:
            requests:
              memory: "128Mi"
              cpu: "250m"
            limits:
              memory: "256Mi"
              cpu: "500m"

Con este template, un desarrollador solo tiene que llenar los campos en la UI de Backstage y automáticamente se genera el deployment con las mejores prácticas. Nada de copiar y pegar YAMLs de un lado a otro.

Así se ve la UI de Backstage

Para que te hagas una idea de cómo luce Backstage en acción, aquí te dejo algunas capturas:

Vista del Software Catalog

Vista del Software Catalog

Formulario de un Software Template

Formulario de un Software Template

Cierre

Y bueno, hasta aquí llegamos con esta primera entrega de la Backstage Series. Esto fue apenas un acercamiento a lo que esta tecnología puede ofrecer. Como viste, Backstage no es solo una herramienta más — es una plataforma que puede transformar la forma en que tu equipo gestiona servicios, documentación e infraestructura.

En las siguientes entregas de esta serie vamos a ir más profundo. Vamos a explorar temas como:

  • Cómo configurar el Software Catalog con entidades reales.
  • Crear templates más avanzados con múltiples pasos.
  • Integrar Backstage con Kubernetes y ArgoCD.
  • Personalizar la UI y crear tus propios plugins.

Así que quédate pendiente, porque esto apenas comienza. Si tienes dudas o quieres que cubra algo en particular, no dudes en dejar tu comentario.

¡Nos vemos en la siguiente! 🚀

Actualizado el 2026-03-21
 Backstage, DevOps, Kubernetes, Platform Engineering, GitOps, GitHub
Regresar | Inicio