Un portal de desarrollo vale lo que su catálogo, y los catálogos se pudren

El portal se lanza con entusiasmo. Cuarenta servicios aparecen en el catálogo, cada uno con su dueño, su README y enlaces a sus paneles. Ocho meses después, doce de esos servicios ya no existen, faltan seis nuevos, un tercio de los dueños ha cambiado de equipo, y los ingenieros han vuelto a preguntar en el chat quién lleva la API de pagos.

La herramienta no tenía nada malo. El catálogo lo mantenían personas, y las personas actualizan un catálogo exactamente el tiempo que alguien esté mirando.

Los tres problemas que sí resuelve

Sé específico con estos, porque un portal justificado como "experiencia de desarrollo" no tiene forma de evaluarse.

Encontrar quién es dueño de un servicio. A las tres de la madrugada, o cuando llega un informe de vulnerabilidad, o cuando hay que retirar una API, la pregunta es de quién es esto y cómo lo localizo. En una organización con más de veinte o treinta servicios esto es genuinamente difícil y genuinamente caro, y es el problema para el que existe el catálogo.

Crear un servicio nuevo con el andamiaje correcto. Las plantillas de software generan un repositorio con el pipeline, el cableado de observabilidad, los valores de seguridad por defecto, los metadatos de propiedad y la configuración de despliegue ya correctos. El valor no es ahorrar una tarde de configuración, es que el servicio número cincuenta esté configurado igual que el primero en vez de copiado de aquel en el que el ingeniero se fijó por casualidad.

Documentación que vive con el código. Documentación escrita en markdown dentro del repositorio, compilada y publicada junto al servicio. La documentación en un wiki está desactualizada porque actualizarla es un acto aparte; la del repositorio al menos aparece en el pull request que cambió el comportamiento.

Si no puedes señalar cuál de estos tres es tu problema, todavía no necesitas un portal.

El catálogo hay que alimentarlo, no rellenarlo

Esta es la diferencia entre un portal que sobrevive y uno que se abandona, y es una única decisión de diseño.

Haz que los metadatos de cada servicio sean un fichero en su propio repositorio, descubierto automáticamente. El equipo dueño del código es dueño de la entrada, cambia en el mismo pull request que el cambio que describe, y un servicio que se borra se lleva su entrada con él.

Y después ve más allá y deriva lo que puedas de sistemas que ya son verdad. La propiedad, del fichero de responsables de código. El estado de despliegue y la versión, del sistema de despliegue. Las dependencias, de la malla de servicios o de los datos de trazado. Los recursos de nube, de las definiciones de infraestructura. Todo lo que derivas es una cosa que no puede desactualizarse.

La regla que lo mantiene honesto: si un campo lo tiene que teclear una persona y esa persona no lo ve en su trabajo diario, estará mal en dos trimestres. O lo derivas o lo borras.

Sigue la frescura del catálogo como métrica real. El porcentaje de entradas cuyo repositorio de origen se ha tocado en los últimos noventa días, y el número de servicios desplegados sin entrada en el catálogo. Si nadie vigila esos dos números, nadie está manteniendo el catálogo.

Las plantillas son donde está la recompensa

De los tres problemas, el andamiaje es el de retorno más claro, y es por el que hay que empezar.

Una plantilla que crea un repositorio con el pipeline, un fichero de construcción de imagen, extremos de salud, registro estructurado con correlación de trazas, el fichero de propiedad, un panel y un runbook inicial convierte un conjunto de estándares de documentación en un valor por defecto. Los ingenieros obtienen la configuración correcta tomando el camino fácil, que es la única forma fiable de que se extiendan los estándares.

El modo de fallo son las plantillas que se separan del estándar actual, de modo que un servicio creado el año pasado tiene el pipeline viejo y nadie lo actualiza. Versiona las plantillas y da una forma de ver qué servicios se crearon desde una versión antigua. Algunos equipos van más allá y convierten partes del andamiaje en un módulo compartido que los servicios consumen en vez de copiar, lo que convierte una actualización en una subida de versión.

Es el mismo razonamiento que el diseño de módulos en Terraform: el andamiaje copiado diverge, el consumido no.

El coste que no se planifica

Backstage es un marco, no un producto que instalas. Lo despliegas, escribes complementos, lo mantienes, lo actualizas, y las actualizaciones en un ecosistema de complementos rompen cosas de vez en cuando.

Eso significa un dueño con nombre y una fracción de persona de forma permanente. Un portal sin dueño es el abandono más predecible de la ingeniería de plataforma, porque se degrada despacio y nadie se da cuenta hasta que es inútil.

Presupuesta con honestidad: unas semanas hasta una primera versión útil, y mantenimiento continuo después. Si no puedes comprometerte con la parte continua, no empieces.

Existen ya alternativas gestionadas y comerciales, incluidas ofertas alojadas y otros productos de portal interno, y el intercambio es el de siempre: menos control y menos personalización a cambio de mucha menos carga operativa. Para un equipo que quiere el catálogo y las plantillas sin el marco, esa suele ser la decisión correcta.

Cuándo basta con un repositorio y un README

Por debajo de unos quince servicios con uno o dos equipos, un portal es gasto. Las respuestas que da ya están en la cabeza de todos, y el catálogo es una hoja de cálculo que es correcta porque alguien puede verla entera de una vez.

La versión barata que cubre la mayor parte del valor: un fichero de responsables de código en cada repositorio, un repositorio plantilla que la gente clona, una única página que lista servicios con dueños y enlaces, y la convención de que la documentación vive en el repositorio. No cuesta nada y se degrada con elegancia.

Adopta un portal cuando la pregunta "de quién es esto" deje de tener respuesta obvia, que en nuestra experiencia es entre veinte y treinta servicios o cuando llega el segundo o el tercer equipo.

Lo que se olvida

• No sustituye a la propiedad. Una entrada de catálogo que nombra a un equipo que no es dueño de verdad empeora el problema, porque ahora parece contestado.
• El control de acceso importa. Un portal que agrega recursos de nube, pipelines y paneles se convierte en una vista única muy atractiva de tu entorno para quien consiga entrar.
• La adopción es la parte difícil. Un portal que nadie abre es peor que ningún portal, porque absorbió el esfuerzo. Ponlo donde ya están los ingenieros y haz que una cosa sea genuinamente más fácil desde el primer día.
• Los complementos envejecen. Cada complemento es una dependencia con alguien que lo mantiene y que puede irse.
• La tentación de la tarjeta de puntuación. Las tarjetas de madurez son populares y se convierten en un juego. Si las usas, mide un número pequeño de cosas que importen de verdad, como si un servicio tiene dueño y runbook.

Qué hacer esta semana

Elige tres servicios al azar de tus despliegues de producción e intenta responder, en menos de dos minutos cada uno y sin preguntar a nadie, quién es su dueño y dónde está su runbook. Cronométrate. Si alguno de los tres lleva más de dos minutos, has medido el problema que resuelve un catálogo, y el primer arreglo es un fichero de responsables de código, no una plataforma. Lo trabajamos en la fase de plataforma de un proyecto cloud.