El primer dominio

Un dominio es el nivel del catálogo de Airframe que está debajo de un recorrido y encima de sus contextos y productos, y cada producto pertenece a uno. Agregar un dominio empieza con unos pocos archivos pequeños en el catálogo, pero no termina ahí: un dominio también necesita una fábrica de proyectos y una raíz de GitLab propias, que son cambios en la plataforma misma. Esta página enumera cada paso, dice cuáles deriva la plataforma por su cuenta y nombra quién aprueba el resto.

Las palabras recorrido, dominio y contexto se explican en cómo se divide la organización. El ejemplo es el recorrido settle de la organización de demostración, su dominio billing y el contexto tax que contiene.

1. Los archivos del catálogo

Todos los archivos van en un solo merge request al repositorio del catálogo.

Archivo	Lo que dice
`catalog.yaml`	El recorrido agregado a `journeys`, si es nuevo, y el dominio agregado a `domains` como ruta, como `settle/billing`
`journeys/settle.yaml`	Los líderes del recorrido y una descripción de una línea
`domains/settle.billing.yaml`	Los líderes del dominio, una descripción, y si tiene un subárbol restringido para los productos que no están abiertos al resto de la organización
`contexts/settle.billing.tax.yaml`	Los líderes del contexto y una descripción
`people/<person>.yaml`	Cada líder, si todavía no está en el catálogo
`teams/<team>.yaml`	Un equipo que vive en el contexto nuevo, para que pueda gestionar productos ahí

El archivo de un dominio se ve así:

domain: billing
journey: settle
leads: [noa.brightwater]
description: invoices, payments and the taxes on them
restricted_subtree: true

Los líderes son personas, nombradas por su identificador en el catálogo. Los líderes pueden hacer merge en cada producto debajo de su nivel, y los líderes de un contexto y de un dominio aprueban las entradas de sus productos, así que elige a personas que vayan a revisar.

El lint del catálogo rechaza un archivo cuyo nombre y cuyos campos no coinciden, un nivel cuyo archivo padre no existe, un líder que no es una persona del catálogo o que se fue de la organización, y un recorrido o un dominio de catalog.yaml sin su archivo (aplicado). Los nombres son cortos y en minúsculas: un recorrido tiene de 3 a 10 letras, un dominio de 3 a 8 y un contexto de 3 a 12 caracteres. Un dominio pequeño igual declara un contexto, con el nombre del dominio, como billing/billing.

Quién aprueba: dos miembros del equipo de la plataforma, porque el modelo de responsables del catálogo le asigna los archivos de la jerarquía a la plataforma, con dos aprobaciones. Hoy quien aprueba en segundo lugar es la segunda cuenta del mantenedor: el mecanismo se aplica, pero la separación entre dos personas todavía no es real.

2. Lo que la plataforma deriva por su cuenta

Cuando el merge request se integra, el pipeline del catálogo inicia la cadena de reconciliadores, que lee los archivos nuevos:

roots/folders de landing-zone crea una carpeta para el recorrido, el dominio y el contexto;
roots/groups de landing-zone crea un grupo de Google para los líderes de cada nivel, con sus miembros;
roots/network de landing-zone le da al dominio dos subredes en cada red, una para el tráfico de salida de sus servicios de Cloud Run y otra para los servicios internos.

La raíz de red numera el bloque de direcciones de cada dominio según el orden alfabético de las rutas de los dominios. Una ruta nueva que quede antes que una existente, como fulfil/returns antes que fulfil/shipping, movería las subredes de ese dominio y las de todos los que vienen después, así que lee el plan de la raíz de red en este merge request antes de que se aplique. El plan además tiene lugar para ocho dominios: un noveno ocuparía el bloque del rango de servicios privados que usa Cloud SQL, así que antes hay que cambiar el plan de direcciones.

3. Los grupos de GitLab, por el administrador

Los grupos del recorrido, del dominio y del contexto, y la cuenta de fábrica del dominio, la cuenta de servicio de GitLab que crea los repositorios de los productos del dominio, viven en roots/gitlab de control-plane. Esa raíz necesita el rol Owner de GitLab, así que solo se aplica con el procedimiento excepcional: un mantenedor la aplica desde una laptop con un token de un día de la cuenta de administración de GitLab, con una concesión de tiempo limitado, y revoca el token después.

La misma aplicación crea un secreto llamado gitlab-factory-<journey>-<domain>-token. El valor del secreto lo agrega un mantenedor a partir de la salida de la raíz, con una concesión, y nunca se muestra. La aplicación deja una fila en docs/bootstrap-log.md de landing-zone, con el identificador de la concesión.

4. La fábrica de proyectos, en landing-zone

Un merge request en landing-zone, aprobado por el equipo de la plataforma:

una raíz nueva, roots/project-factory/settle-billing/, copiada de la fábrica de un dominio existente, como la segunda y la tercera fábrica de la organización de demostración se copiaron de la primera;
el job de la fábrica en .gitlab-ci.yml;
la identidad de la fábrica, factory-settle-billing@, en roots/wif, con sus roles en la carpeta del dominio, Billing Account User en la cuenta de facturación, y sus lecturas del estado de otras raíces, más los permisos que dejan que las raíces que leen el estado de cada fábrica lean también el de la nueva: las raíces de red, de perímetros, de GitLab, del ejecutor, del constructor de confianza, de telemetría y del catálogo de arquitectura;
la fábrica nueva agregada a las listas de roots/network, roots/perimeters y roots/state, y, para un recorrido nuevo, el recorrido agregado a journey_zones de la raíz de red, que le da una zona DNS.

roots/wif es una de las tres raíces que se aplican desde una laptop: un mantenedor la aplica con la concesión de aplicación de la plataforma y la concesión de organización, las dos aprobadas por otro miembro del grupo de la plataforma, y anota los identificadores de las concesiones en el registro. El resto se aplica por pipeline.

5. La raíz de GitLab del dominio, en control-plane

Un merge request en control-plane, aprobado por el equipo de la plataforma:

una raíz nueva, roots/gitlab-config-settle-billing/, que crea los repositorios de los productos del dominio como la cuenta de fábrica y sube sus primeros commits;
su job de apply y su job de generación en .gitlab-ci.yml;
la fábrica nueva agregada a las listas de la raíz del ejecutor: su identidad, para que pueda publicar la salida Ready de cada producto, y su estado, que lee la raíz del ejecutor;
la fábrica nueva agregada a domain_factory_prefixes en roots/trusted-builder, para que los productos del dominio puedan leer los registros de imágenes y verificar las atestaciones.

6. La observabilidad, en operations

Un merge request en operations, aprobado por el equipo de la plataforma: la fábrica nueva agregada a las listas de fábricas de dominio que leen roots/telemetry y roots/eventcatalog.

7. Para un recorrido nuevo, en security-policies

Solo cuando el recorrido es nuevo: un merge request en security-policies agrega el id del grupo del recorrido al alcance de la política que inyecta los controles de los productos, en .gitlab/security-policies/policy.yml. Quién aprueba: un mantenedor que no lo escribió. Sin esto, los productos del recorrido nuevo ejecutan sus pipelines sin los jobs de producto inyectados: la validación de sus raíces y su evidencia de compilación y de pruebas.

En resumen

Paso	Cómo, quién aprueba y el registro
Los archivos del catálogo	Un merge request en el catálogo. Aprueba: dos del equipo de la plataforma. Registro: el merge request.
Carpetas, grupos de líderes, subredes	Derivados por la cadena. Aprueba: nadie más. Registro: los pipelines.
Grupos de GitLab y la cuenta de fábrica	El procedimiento excepcional. Aprueba: otro miembro del grupo de la plataforma, para la concesión. Registro: `docs/bootstrap-log.md`.
La fábrica de proyectos y su identidad	Un merge request en landing-zone, `roots/wif` desde una laptop. Aprueba: el equipo de la plataforma; las concesiones, otro miembro. Registro: `docs/bootstrap-log.md` para la aplicación desde la laptop.
La raíz de GitLab del dominio	Un merge request en control-plane. Aprueba: el equipo de la plataforma. Registro: el merge request.
Las listas de observabilidad	Un merge request en operations. Aprueba: el equipo de la plataforma. Registro: el merge request.
Los controles de producto de un recorrido nuevo	Un merge request en security-policies. Aprueba: un mantenedor que no lo escribió. Registro: el merge request.

El segundo y el tercer dominio de la organización de demostración se agregaron así, y la documentación del catálogo de la plataforma cuenta una raíz de fábrica y una raíz de GitLab del dominio entre lo que deriva cada dominio. Hoy se escriben a mano, copiando, en merge requests. Cuando existen, el primer producto es un solo archivo del catálogo.

Dónde está

En el repositorio catalog:

En el repositorio landing-zone:

En el repositorio control-plane: