Como os repositórios se encaixam

O Airframe não é um programa só, mas sete repositórios git, cada um cuidando de uma parte da plataforma, mais o repositório deste site. Todos são públicos no GitLab, em gitlab.com/projectairframe. Esta página é o mapa: para que serve cada repositório, como eles dependem uns dos outros, e quem pode mudar cada um. Depois, cada repositório tem sua própria página.

Os sete repositórios, em uma frase cada

• catalog guarda a intenção: quais produtos, equipes e pessoas existem, e quem é responsável pelo quê. Todo o resto deriva dele.
• landing-zone constrói a base na nuvem: as pastas e políticas da organização, as redes, as fábricas de projetos que criam os projetos de cada produto, as identidades e o registro de auditoria. Ele também guarda a especificação e o manual da plataforma.
• control-plane opera a maquinaria da mudança: o controle de aprovação, o executor, os componentes de pipeline que cada repositório inclui, o pacote de políticas, e as raízes que configuram o GitLab.
• golden-path guarda o template de produto, que gera o repositório de um produto novo em Java, Node ou Python, e os módulos de Terraform com os quais os produtos são construídos.
• operations opera o que mantém os produtos observáveis: o fluxo de telemetria, os painéis e as regras de alerta no Grafana, e os jobs agendados, como o relatório diário de custos.
• platform-skills ensina a cada agente de código os padrões da plataforma, como skills que um agente de código carrega, cada uma com testes.
• security-policies guarda as políticas do GitLab para o grupo todo: os jobs injetados em cada pipeline, e as regras sobre quem precisa aprovar um merge.

O repositório website guarda este site. Ele não faz parte da plataforma, mas roda sobre ela: é implantado pelo mesmo controle de aprovação e pelo mesmo pipeline que todo o resto.

Como eles se conectam

Leia o mapa a partir da esquerda.

O catálogo move três repositórios. Quando uma mudança no catálogo é integrada, seu pipeline inicia, um de cada vez, os pipelines de landing-zone, operations e control-plane. Cada um lê o catálogo e faz sua própria parte corresponder a ele: projetos e grupos, depois painéis, depois repositórios. A página de reconciliadores explica essa cadeia.

Cinco repositórios dão forma a cada repositório de produto. O repositório de um produto é gerado a partir do template do golden-path. Seu pipeline inclui os componentes do control-plane, que planejam, aplicam, compilam e promovem. O security-policies injeta a validação e a verificação do controle de aprovação, que o produto não pode remover. E os projetos, identidades e painéis do produto vêm do landing-zone e do operations.

As versões amarram as ferramentas. control-plane, golden-path, os módulos, security-policies e platform-skills são lançados juntos, como uma versão da plataforma que nomeia o commit exato de cada um. O arquivo de pipeline de cada repositório diz qual versão ele usa.

O platform-skills é usado pelas ferramentas das pessoas, não pelos pipelines. O agente de código de um desenvolvedor carrega as skills enquanto trabalha em qualquer repositório; as skills são testadas contra o pacote de políticas da versão que fixam.

Quem muda cada repositório

Toda mudança em todo repositório é um merge request, e nenhum pode ser integrado só com a aprovação do seu autor. As diferenças estão em quem precisa aprovar:

• Os repositórios da plataforma, landing-zone, control-plane, golden-path, operations, platform-skills e website, precisam da aprovação da equipe de plataforma. O design pede duas aprovações; enquanto uma só pessoa opera a plataforma é uma, e o número volta a dois no catálogo ativo quando um segundo mantenedor entrar.
• O catálogo segue seu próprio modelo de responsáveis: o arquivo de um produto é aprovado pela sua equipe ou pelos seus líderes, um aumento de orçamento por um líder do domínio, uma mudança de ciclo de vida por duas pessoas, e a estrutura do catálogo por dois membros da equipe de plataforma. A página do catálogo lista as regras.
• O security-policies é a via de emergência. Ele guarda as próprias regras de aprovação, então é o único repositório que o controle de aprovação não julga, e os seus próprios pipelines não levam o gate:integrity, então ele é integrado mesmo quando o controle não pode ser alcançado. O que o protege é a aprovação de uma pessoa nomeada, nunca a do autor. Sua página explica por quê.

Hoje, em todos os repositórios menos o security-policies, a aprovação do controle também é exigida (a política de aprovação nomeia cada repositório que cobre, e um novo entra por merge request), e o controle só a dá quando os responsáveis que o catálogo nomeia aprovaram o último commit.

Quem aplica o quê

A maioria das raízes de Terraform da plataforma é aplicada pelo próprio pipeline do seu repositório, na branch main protegida, cada uma com sua própria identidade. Algumas não:

• três raízes do landing-zone, as políticas da organização, a configuração de auditoria e as identidades, são aplicadas a partir de um notebook com uma concessão de tempo limitado, e são planejadas todo dia para pegar qualquer desvio;
• a raiz gitlab do control-plane, que guarda as poucas configurações do GitLab fixadas na inicialização, é aplicada a partir de um notebook com o token de curta duração do administrador, e cada execução é registrada.

A página de cada repositório diz como suas raízes são aplicadas.