Cómo encajan los repositorios

Airframe no es un solo programa sino siete repositorios git, cada uno a cargo de una parte de la plataforma, más el repositorio de este sitio web. Todos son públicos en GitLab, en gitlab.com/projectairframe. Esta página es el mapa: para qué sirve cada repositorio, cómo dependen unos de otros, y quién puede cambiar cada uno. Después, cada repositorio tiene su propia página.

Los siete repositorios, en una oración cada uno

• catalog guarda la intención: qué productos, equipos y personas existen, y quién es responsable de qué. Todo lo demás se deriva de él.
• landing-zone construye la base en la nube: las carpetas y políticas de la organización, las redes, las fábricas de proyectos que crean los proyectos de cada producto, las identidades y el registro de auditoría. También guarda la especificación y el manual de la plataforma.
• control-plane opera la maquinaria del cambio: la compuerta de aprobación, el ejecutor, los componentes de pipeline que incluye cada repositorio, el paquete de políticas, y las raíces que configuran GitLab.
• golden-path guarda la plantilla de producto, que genera el repositorio de un producto nuevo en Java, Node o Python, y los módulos de Terraform con los que se construyen los productos.
• operations opera lo que mantiene observables a los productos: el flujo de telemetría, los paneles y las reglas de alerta en Grafana, y los trabajos programados como el informe diario de costos.
• platform-skills le enseña a cada agente de código los patrones de la plataforma, como skills que un agente de código carga, cada una con pruebas.
• security-policies guarda las políticas de GitLab para todo el grupo: los trabajos que se inyectan en cada pipeline, y las reglas sobre quién debe aprobar un merge.

El repositorio website guarda este sitio. No es parte de la plataforma, pero funciona sobre ella: se despliega con la misma compuerta de aprobación y el mismo pipeline que todo lo demás.

Cómo se conectan

Lee el mapa desde la izquierda.

El catálogo mueve a tres repositorios. Cuando se integra un cambio en el catálogo, su pipeline inicia por turno los pipelines de landing-zone, operations y control-plane. Cada uno lee el catálogo y hace que su propia parte coincida con él: proyectos y grupos, después paneles, después repositorios. La página de reconciliadores explica esa cadena.

Cinco repositorios dan forma a cada repositorio de producto. El repositorio de un producto se genera desde la plantilla de golden-path. Su pipeline incluye los componentes de control-plane, que planifican, aplican, compilan y promueven. security-policies inyecta la validación y la verificación de la compuerta, que el producto no puede quitar. Y los proyectos, identidades y paneles del producto vienen de landing-zone y operations.

Las versiones atan las herramientas. control-plane, golden-path, los módulos, security-policies y platform-skills se publican juntos, como una versión de la plataforma que nombra el commit exacto de cada uno. El archivo de pipeline de cada repositorio dice qué versión usa.

platform-skills lo usan las herramientas de las personas, no los pipelines. El agente de código de un desarrollador carga las skills mientras trabaja en cualquier repositorio; las skills se prueban contra el paquete de políticas de la versión que fijan.

Quién cambia cada repositorio

Todo cambio en todo repositorio es un merge request, y ninguno se puede integrar solo con la aprobación de su autor. Las diferencias están en quién debe aprobar:

• Los repositorios de la plataforma, landing-zone, control-plane, golden-path, operations, platform-skills y website, necesitan la aprobación del equipo de plataforma. El diseño pide dos aprobaciones; mientras una sola persona opera la plataforma es una, y el número vuelve a dos en el catálogo en vivo cuando se sume un segundo mantenedor.
• El catálogo sigue su propio modelo de responsables: el archivo de un producto lo aprueba su equipo o sus líderes, una suba de presupuesto un líder del dominio, un cambio de ciclo de vida dos personas, y la estructura del catálogo dos miembros del equipo de plataforma. La página del catálogo enumera las reglas.
• security-policies es la vía de emergencia. Guarda las propias reglas de aprobación, así que es el único repositorio que la compuerta de aprobación no juzga, y sus propios pipelines no llevan gate:integrity, así que se integra aunque no se pueda llegar a la compuerta. Lo protege la aprobación de una persona con nombre, nunca la del autor. Su página explica por qué.

Hoy, en todos los repositorios menos security-policies, también se exige la aprobación de la compuerta (la política de aprobación nombra cada repositorio que cubre, y uno nuevo se suma por merge request), y la compuerta la da solo cuando los responsables que nombra el catálogo aprobaron el último commit.

Quién aplica qué

La mayoría de las raíces de Terraform de la plataforma las aplica el propio pipeline de su repositorio, en la rama main protegida, cada una con su propia identidad. Algunas no:

• tres raíces de landing-zone, las políticas de la organización, la configuración de auditoría y las identidades, se aplican desde una laptop con una concesión de tiempo limitado, y se planifican todos los días para detectar cualquier deriva;
• la raíz gitlab de control-plane, que guarda las pocas configuraciones de GitLab fijadas en el arranque, se aplica desde una laptop con el token de corta duración del administrador, y cada ejecución queda registrada.

La página de cada repositorio dice cómo se aplican sus raíces.