O primeiro domínio

Um domínio é o nível do catálogo do Airframe que fica abaixo de uma jornada e acima dos seus contextos e produtos, e todo produto pertence a um. Adicionar um domínio começa com alguns arquivos pequenos no catálogo, mas não termina aí: um domínio também precisa de uma fábrica de projetos e de uma raiz do GitLab próprias, que são mudanças na própria plataforma. Esta página lista cada passo, diz quais a plataforma deriva sozinha e nomeia quem aprova o resto.

As palavras jornada, domínio e contexto são explicadas em como a organização é dividida. O exemplo é a jornada settle da organização de demonstração, o domínio billing dela e o contexto tax que ele contém.

1. Os arquivos do catálogo

Todos os arquivos vão em um único merge request para o repositório do catálogo.

Arquivo	O que ele diz
`catalog.yaml`	A jornada adicionada a `journeys`, se for nova, e o domínio adicionado a `domains` como caminho, como `settle/billing`
`journeys/settle.yaml`	Os líderes da jornada e uma descrição de uma linha
`domains/settle.billing.yaml`	Os líderes do domínio, uma descrição, e se ele tem uma subárvore restrita para os produtos que não são abertos ao resto da organização
`contexts/settle.billing.tax.yaml`	Os líderes do contexto e uma descrição
`people/<person>.yaml`	Cada líder, se ainda não estiver no catálogo
`teams/<team>.yaml`	Uma equipe que vive no contexto novo, para poder gerenciar produtos ali

O arquivo de um domínio é assim:

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

Os líderes são pessoas, chamadas pelo identificador delas no catálogo. Os líderes podem fazer merge em todo produto abaixo do seu nível, e os líderes de um contexto e de um domínio aprovam as entradas dos seus produtos, então escolha pessoas que vão revisar.

O lint do catálogo recusa um arquivo cujo nome e cujos campos não batem, um nível cujo arquivo pai não existe, um líder que não é uma pessoa do catálogo ou que saiu da organização, e uma jornada ou um domínio do catalog.yaml sem o seu arquivo (aplicado). Os nomes são curtos e em minúsculas: uma jornada tem de 3 a 10 letras, um domínio de 3 a 8 e um contexto de 3 a 12 caracteres. Um domínio pequeno ainda declara um contexto, com o nome do domínio, como billing/billing.

Quem aprova: dois membros da equipe da plataforma, porque o modelo de responsáveis do catálogo entrega os arquivos da hierarquia à plataforma, com duas aprovações. Hoje quem aprova em segundo lugar é a segunda conta do mantenedor: o mecanismo é aplicado, mas a separação entre duas pessoas ainda não é real.

2. O que a plataforma deriva sozinha

Quando o merge request é integrado, o pipeline do catálogo inicia a cadeia de reconciliadores, que lê os arquivos novos:

o roots/folders do landing-zone cria uma pasta para a jornada, o domínio e o contexto;
o roots/groups do landing-zone cria um grupo do Google para os líderes de cada nível, com seus membros;
o roots/network do landing-zone dá ao domínio duas sub-redes em cada rede, uma para o tráfego de saída dos seus serviços do Cloud Run e outra para os serviços internos.

A raiz de rede numera o bloco de endereços de cada domínio pela ordem alfabética dos caminhos dos domínios. Um caminho novo que fique antes de um existente, como fulfil/returns antes de fulfil/shipping, moveria as sub-redes desse domínio e as de todos os que vêm depois, então leia o plano da raiz de rede neste merge request antes que ele seja aplicado. O plano também tem espaço para oito domínios: um nono ocuparia o bloco da faixa de serviços privados que o Cloud SQL usa, então o plano de endereços precisa mudar antes.

3. Os grupos do GitLab, pelo administrador

Os grupos da jornada, do domínio e do contexto, e a conta de fábrica do domínio, a conta de serviço do GitLab que cria os repositórios dos produtos do domínio, ficam no roots/gitlab do control-plane. Essa raiz precisa do papel Owner do GitLab, então só é aplicada pelo procedimento excepcional: um mantenedor a aplica de um notebook com um token de um dia da conta de administração do GitLab, com uma concessão de tempo limitado, e revoga o token depois.

A mesma aplicação cria um segredo chamado gitlab-factory-<journey>-<domain>-token. O valor do segredo é adicionado por um mantenedor a partir da saída da raiz, com uma concessão, e nunca é exibido. A aplicação deixa uma linha no docs/bootstrap-log.md do landing-zone, com o identificador da concessão.

4. A fábrica de projetos, no landing-zone

Um merge request no landing-zone, aprovado pela equipe da plataforma:

uma raiz nova, roots/project-factory/settle-billing/, copiada da fábrica de um domínio existente, como a segunda e a terceira fábricas da organização de demonstração foram copiadas da primeira;
o job da fábrica no .gitlab-ci.yml;
a identidade da fábrica, factory-settle-billing@, no roots/wif, com seus papéis na pasta do domínio, Billing Account User na conta de faturamento, e suas leituras do estado de outras raízes, mais as permissões que deixam as raízes que leem o estado de cada fábrica lerem também o da nova: as raízes de rede, de perímetros, do GitLab, do executor, do construtor confiável, de telemetria e do catálogo de arquitetura;
a fábrica nova adicionada às listas do roots/network, do roots/perimeters e do roots/state, e, para uma jornada nova, a jornada adicionada ao journey_zones da raiz de rede, que dá a ela uma zona de DNS.

O roots/wif é uma das três raízes aplicadas de um notebook: um mantenedor a aplica com a concessão de aplicação da plataforma e a concessão de organização, as duas aprovadas por outro membro do grupo da plataforma, e anota os identificadores das concessões no registro. O resto é aplicado por pipeline.

5. A raiz do GitLab do domínio, no control-plane

Um merge request no control-plane, aprovado pela equipe da plataforma:

uma raiz nova, roots/gitlab-config-settle-billing/, que cria os repositórios dos produtos do domínio como a conta de fábrica e envia os primeiros commits deles;
o job de apply e o job de geração dela no .gitlab-ci.yml;
a fábrica nova adicionada às listas da raiz do executor: a identidade dela, para que possa publicar a saída Ready de cada produto, e o estado dela, que a raiz do executor lê;
a fábrica nova adicionada a domain_factory_prefixes no roots/trusted-builder, para que os produtos do domínio possam ler os registros de imagens e verificar os atestados.

6. A observabilidade, no operations

Um merge request no operations, aprovado pela equipe da plataforma: a fábrica nova adicionada às listas de fábricas de domínio que o roots/telemetry e o roots/eventcatalog leem.

7. Para uma jornada nova, no security-policies

Só quando a jornada é nova: um merge request no security-policies adiciona o id do grupo da jornada ao escopo da política que injeta as verificações dos produtos, em .gitlab/security-policies/policy.yml. Quem aprova: um mantenedor que não o escreveu. Sem isso, os produtos da jornada nova rodam os pipelines sem os jobs de produto injetados: a validação das raízes deles e a evidência de build e de testes.

Somando tudo

Passo	Como, quem aprova e o registro
Os arquivos do catálogo	Um merge request no catálogo. Aprova: dois da equipe da plataforma. Registro: o merge request.
Pastas, grupos de líderes, sub-redes	Derivados pela cadeia. Aprova: ninguém mais. Registro: os pipelines.
Grupos do GitLab e a conta de fábrica	O procedimento excepcional. Aprova: outro membro do grupo da plataforma, para a concessão. Registro: `docs/bootstrap-log.md`.
A fábrica de projetos e a identidade dela	Um merge request no landing-zone, `roots/wif` de um notebook. Aprova: a equipe da plataforma; as concessões, outro membro. Registro: `docs/bootstrap-log.md` para a aplicação do notebook.
A raiz do GitLab do domínio	Um merge request no control-plane. Aprova: a equipe da plataforma. Registro: o merge request.
As listas de observabilidade	Um merge request no operations. Aprova: a equipe da plataforma. Registro: o merge request.
As verificações de produto de uma jornada nova	Um merge request no security-policies. Aprova: um mantenedor que não o escreveu. Registro: o merge request.

O segundo e o terceiro domínios da organização de demonstração foram adicionados assim, e a documentação do catálogo da plataforma conta uma raiz de fábrica e uma raiz do GitLab do domínio entre o que cada domínio deriva. Hoje elas são escritas à mão, por cópia, em merge requests. Quando elas existem, o primeiro produto é um único arquivo do catálogo.

Onde fica

No repositório catalog:

No repositório landing-zone:

No repositório control-plane: