golden-path

O repositório golden-path guarda o jeito recomendado de construir um produto no Airframe: um template que gera o repositório de um produto novo, e os módulos de Terraform que esse produto usa para criar seus serviços, seu banco de dados e seus segredos. Um produto gerado a partir dele começa com uma aplicação funcionando, sua infraestrutura, um pipeline feito com os componentes da plataforma e um runbook, implantando no Cloud Run atrás do login único. É um padrão, não uma exigência: depois do primeiro commit, o código é da equipe.

Para que serve

Todo produto precisa das mesmas conexões básicas: projetos ligados à plataforma, um serviço com logs estruturados e telemetria, um banco de dados com backups, segredos por nome, um pipeline. Escrever tudo de novo para cada produto é lento e se desvia. O golden path escreve isso uma vez, mantém testado, e entrega a cada produto novo uma cópia que já passa em todas as verificações.

O que ele contém

O template: um template do Copier (o Copier gera um projeto a partir de um template e de um conjunto de respostas) com uma resposta stack para três pilhas: Node (NestJS e React), Python (o template full-stack do FastAPI) e Java (Spring PetClinic). Tudo o que fica fora da pasta da aplicação é comum às três: as raízes do Terraform, o arquivo de pipeline, a descrição do produto para o catálogo de arquitetura, o runbook e as instruções para um agente de código.
Os módulos: service-project e airframe-context, que leem o que a fábrica de projetos criou; cloud-run-service, cloud-sql, secrets, preview-substrate, database-seed e grafana-dashboard. Cada um tem seus próprios testes contra provedores simulados.
Os exemplos: um produto gerado para cada pilha, a partir do catálogo ativo, idêntico ao que o template produz hoje.
Um caso que precisa falhar: uma raiz que o pacote de políticas precisa recusar, que prova a cada mudança que o pacote continua funcionando.

Como ele se conecta

O catálogo e o landing-zone o alimentam. Quando um produto é criado, a raiz do GitLab do control-plane roda o template com a entrada do produto no catálogo e sua saída Ready da fábrica de projetos como respostas, e grava o resultado como o primeiro commit do repositório.
Os produtos usam seus módulos. As raízes de um produto chamam os módulos, fixados em um commit, em vez de declarar os recursos da nuvem um por um.
Ele inclui os componentes do control-plane. O arquivo de pipeline gerado inclui só os componentes da plataforma, que é o que o pacote de políticas exige de cada produto.
Ele faz parte de cada versão. Uma versão da plataforma nomeia o commit do template e dos módulos, junto com as outras partes.

Quem o muda, e como

As mudanças são merge requests aprovados pela equipe de plataforma, com a aprovação do controle obrigatória. O pipeline é o portão de publicação do template:

sempre que o template, os exemplos ou o pipeline mudam, ele gera de novo os três exemplos a partir do catálogo ativo e falha se forem diferentes dos gravados;
ele compila e testa o exemplo de uma pilha sempre que os arquivos de template dessa pilha, seu exemplo ou o pipeline mudam;
ele roda os testes dos módulos, valida cada exemplo como raiz de produto, e roda o pacote de políticas sobre os exemplos e o caso que precisa falhar.

Os jobs de compilação e testes da plataforma só conhecem essas três pilhas. Um produto em outra pilha, com seu próprio Dockerfile sobre uma imagem base da plataforma, não roda nenhum deles, e seus merge requests falham na exigência de cobertura de testes até que sua entrada no catálogo reduza a cobertura exigida, o que um líder de equipe ou um líder do domínio precisa aprovar. É uma lacuna conhecida.

O repositório não tem raízes próprias e não custa nada parado.

Onde fica

No repositório golden-path: