Despliega Backstage en Kubernetes: Tu Portal de Desarrolladores Interno Multiservicio

Hoy te traigo un proyecto puntero que está arrasando entre equipos DevOps y plataformas: Backstage de Spotify, el portal de desarrolladores más popular para orquestar servicios, documentación, catálogo de APIs, monitoreo y despliegue desde una interfaz central. Vamos a ver cómo puedes levantar tu propio Backstage autohospedado en un Kubernetes en tu VPS y por qué te interesará para centralizar tus proyectos, reducir la fricción y facilitar la colaboración, tanto en entornos corporativos como personales.

¿Qué es Backstage y por qué desplegarlo en Kubernetes?

• Portal central de desarrollo: Catálogo de servicios, documentación viva, plantillas de proyectos y conectores.
• Escalabilidad sencilla: Kubernetes te permite escalar Backstage bajo demanda o integrarlo con otros servicios, SSO o monitorización.
• Personalización y plugins: Añade integraciones como Github, Gitlab, Jenkins, Prometheus, herramientas de CI/CD, y mucho más.
• Plataforma de moda: Adoptada y arropada por la CNCF, Backstage es tendencia y cada mes lanza nuevas funcionalidades.

Arquitectura que desplegaremos

• Backstage App Server corriendo en un Deployment con autoscaling opcional.
• PostgreSQL como base de datos backend para almacenar la información interna.
• Servicios y volúmenes persistentes para soportar reinicios y upgrades.
• Ingress controller para exponer de forma segura la aplicación.
• Opción fácil de integrar un certificado Let’s Encrypt vía anotación o con Cert-Manager.

Ficheros YAML completos para Backstage en Kubernetes

A continuación tienes un ejemplo funcional adaptado para una instalación básica, que puedes personalizar. Incluye variables clave para el dominio y credenciales.

1. Secret para claves de la base de datos

apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
type: Opaque
data:
  POSTGRES_USER: YmFja3N0YWdl
  POSTGRES_PASSWORD: c2VjdXJlcGFzcw==
  POSTGRES_DB: YmFja3N0YWdlX2Ri
  # Valores: echo -n 'usuario' | base64

2. PostgreSQL Deployment y PVC

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
spec:
  selector:
    matchLabels:
      app: postgres
  replicas: 1
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:16
        envFrom:
        - secretRef:
            name: postgres-secret
        ports:
        - containerPort: 5432
        volumeMounts:
        - mountPath: /var/lib/postgresql/data
          name: db-storage
      volumes:
      - name: db-storage
        persistentVolumeClaim:
          claimName: postgres-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
spec:
  ports:
  - port: 5432
  selector:
    app: postgres

3. Backstage Deployment y Service

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backstage
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backstage
  template:
    metadata:
      labels:
        app: backstage
    spec:
      containers:
      - name: backstage
        image: backstage/backstage:latest
        env:
        - name: POSTGRES_HOST
          value: "postgres"
        - name: POSTGRES_USER
          valueFrom:
            secretKeyRef:
              name: postgres-secret
              key: POSTGRES_USER
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: postgres-secret
              key: POSTGRES_PASSWORD
        - name: POSTGRES_DB
          valueFrom:
            secretKeyRef:
              name: postgres-secret
              key: POSTGRES_DB
        - name: BACKSTAGE_APP_BASE_URL
          value: "https://tubackstage.tudominio.com"
        ports:
        - containerPort: 7007
---
apiVersion: v1
kind: Service
metadata:
  name: backstage
spec:
  type: ClusterIP
  ports:
  - port: 80
    targetPort: 7007
  selector:
    app: backstage

4. Ingress para exponer Backstage (con opción Let’s Encrypt)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: backstage-ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"
    # Para cert-manager/Let's Encrypt descomenta esto:
    # cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  tls:
  - hosts:
    - tubackstage.tudominio.com
    secretName: backstage-tls
  rules:
  - host: tubackstage.tudominio.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: backstage
            port:
              number: 80

Cómo desplegarlo paso a paso

1. Crea el Secret y el PVC para la base de datos:
   kubectl apply -f postgres-secret.yaml
kubectl apply -f postgres-pvc.yaml
2. Despliega PostgreSQL:
   kubectl apply -f postgres-deployment.yaml
3. Espera a que esté listo el pod y el servicio de PostgreSQL.
4. Aplica los manifiestos de Backstage (ajusta el nombre de dominio):
   kubectl apply -f backstage-deployment.yaml
5. Configura el Ingress conectado a tu dominio. Si usas Cert-Manager, ajusta las anotaciones para obtener un certificado TLS.
6. Tunea la configuración de Backstage editando su app-config.yaml (hay plugins e integraciones en la documentación oficial).
7. Abre https://tubackstage.tudominio.com y empieza a catalogar y monitorizar tus servicios 🎉

Consejos extra y troubleshooting

• Configuración avanzada: Añade plugins extra (Github, Jenkins, ArgoCD, Sentry, Prometheus…) editando el app-config.yaml y montándolo como ConfigMap.
• Debug: Si Backstage no arranca o no conecta a la base de datos, revisa los logs con kubectl logs deployment/backstage y comprueba que las Secret estén bien codificadas (base64).
• Personalización: Cambia el logo, colores o flujos añadiendo tus propios plugins y recursos estáticos en la imagen (puedes construir tu propia imagen y subirla a Docker Hub o tu registry privado).
• Escalado horizontal: Sube replicas en el deployment según cantidad de usuarios concurrentes.
• Problemas con las rutas: Backstage utiliza pathType: Prefix en el Ingress, ideal para instalarlo en raíz del dominio; si necesitas montar varios portales usa paths distintos (/backstage, /grafana…).
• Seguridad: Implementa Single Sign-On (SSO) e integra RBAC adaptado para tu equipo, y limita acceso con políticas de red.

¡Y eso es todo! Ahora, conviértete en el rey 🦁 de la productividad y documentación interna con tu propio portal Backstage en Kubernetes.
¿Dudas, ideas de integración o quieres que preparemos algún plugin en otro artículo? ¡Déjalo en los comentarios!