Para ajudar a explicar por que motivo as suas equipas de infraestrutura ou aplicações tomam determinadas decisões de design, pode usar registos de decisões de arquitetura (ADRs). Este documento explica quando e como usar os ADRs à medida que cria e executa aplicações no Google Cloud.
Um ADR capta as principais opções disponíveis, os principais requisitos que determinam uma decisão e as próprias decisões de design. Guarda frequentemente ADRs num ficheiro Markdown perto da base de código relevante para essa decisão. Se alguém precisar de compreender o contexto de uma decisão arquitetónica específica, como o motivo pelo qual usa um cluster regional do Google Kubernetes Engine (GKE), pode rever o ADR e, em seguida, o código associado.
Os ADRs também podem ajudar a executar aplicações e serviços mais fiáveis. O ADR ajuda a compreender o seu estado atual e a resolver problemas quando existe um problema. Os ADRs também criam uma coleção de decisões de engenharia para ajudar nas futuras escolhas de decisões e implementações.
Quando usar ADRs
Usa os ADRs para acompanhar as principais áreas que considera importantes para a sua implementação. O seu ADR pode incluir as seguintes categorias:
- Escolhas de produtos específicos, como a escolha entre Pub/Sub e Cloud Tasks.
- Opções e configurações específicas de produtos, como a utilização de clusters do GKE regionais com o Multi Cluster Ingress para aplicações de alta disponibilidade.
- Orientações arquitetónicas gerais, como práticas recomendadas para manifestos de Dockerfile.
Alguns exemplos específicos que podem levar à criação de um ADR podem ser para as seguintes escolhas:
- Como e por que motivo configura a alta disponibilidade (HA) para as suas instâncias do Cloud SQL?
- Como aborda o tempo de atividade dos clusters do GKE? Usa clusters regionais? Usa lançamentos canários? Porquê ou porque não?
À medida que avalia os produtos a usar, o ADR ajuda a explicar cada uma das suas decisões. Pode rever o ADR à medida que a equipa evolui e aprende mais sobre a pilha, e são tomadas ou ajustadas decisões adicionais. Se fizer ajustes, inclua a decisão anterior e o motivo da alteração. Este histórico mantém um registo de como a arquitetura mudou à medida que as necessidades da empresa evoluem ou quando existem novos requisitos técnicos ou soluções disponíveis.
Os seguintes comandos ajudam a saber quando criar ADRs:
- Quando tem um desafio ou uma pergunta técnica e não existe uma base para uma decisão, como uma solução recomendada, um procedimento de operação padrão, um projeto ou uma base de código.
- Quando você ou a sua equipa oferece uma solução que não está documentada num local acessível à equipa.
- Quando existem duas ou mais opções de engenharia e quer documentar as suas ideias e os motivos por detrás da seleção.
Quando escreve um ADR, é útil ter em mente os potenciais leitores. Os leitores principais são membros da equipa que trabalham na tecnologia abrangida pela ADR. Os grupos mais amplos de potenciais leitores do ADR podem incluir equipas adjacentes que queiram compreender as suas decisões, como as equipas de arquitetura e segurança.
Também deve considerar que a aplicação pode mudar de proprietário ou incluir novos membros da equipa. Uma ADR ajuda os novos colaboradores a compreender o contexto das escolhas de engenharia que foram feitas. Uma ADR também facilita o planeamento de alterações futuras.
Formato de um ADR
Um ADR típico inclui um conjunto de capítulos. As ADRs devem ajudar a captar o que considera importante para a aplicação e a sua organização. Alguns ADRs podem ter uma página, enquanto outros requerem uma explicação mais longa.
O exemplo seguinte de um esboço de ADR mostra como pode formatar um ADR para incluir as informações importantes para o seu ambiente:
- Autores e equipa
- Contexto e problema que quer resolver
- Requisitos funcionais e não funcionais que quer abordar
- Potencial percurso crítico do utilizador (CUJ) que a decisão afeta
- Vista geral das principais opções
- A sua decisão e os motivos que levaram à escolha aceite
Para ajudar a manter um registo das decisões, pode incluir uma indicação de tempo para cada decisão para mostrar quando a escolha foi feita.
Como funcionam os ADRs
Os ADRs funcionam melhor quando os engenheiros, os programadores ou os proprietários de aplicações podem aceder facilmente às informações que contêm. Quando têm uma pergunta sobre o motivo pelo qual algo é feito de uma determinada forma, podem consultar o ADR para encontrar a resposta.
Para tornar o ADR acessível, algumas equipas alojam-no numa wiki central que também está acessível aos proprietários de empresas, em vez de no respetivo repositório de controlo de origem. Quando alguém tem uma pergunta sobre uma decisão de engenharia específica, o ADR está disponível para dar respostas.
Os ADRs funcionam bem nos seguintes cenários:
- Incorporação: os novos membros da equipa podem saber facilmente mais sobre o projeto e podem rever o ADR se tiverem dúvidas enquanto aprendem uma nova base de código.
- Evolução da arquitetura: se houver uma transferência da pilha de tecnologia entre equipas, os novos proprietários podem rever as decisões anteriores para compreender o estado atual. A equipa também pode rever decisões anteriores quando tiver acesso a uma nova tecnologia. O ADR pode ajudar as equipas a evitar a repetição dos mesmos pontos de debate e pode ajudar a fornecer contexto histórico quando as equipas revisitam tópicos.
- Partilhar práticas recomendadas: as equipas podem alinhar-se em torno das práticas recomendadas em toda a organização quando os ADRs detalham o motivo pelo qual foram tomadas determinadas decisões e por que motivo foram rejeitadas alternativas.
Uma ADR é frequentemente escrita em Markdown para a manter simples e baseada em texto. Os ficheiros Markdown podem ser incluídos no repositório de controlo de origem com o código da sua aplicação.
Armazene os ADRs perto do código da aplicação, idealmente no mesmo sistema de controlo de versões. À medida que faz alterações ao ADR, pode rever as versões anteriores do controlo de origem, conforme necessário.
Também pode usar outro meio, como um documento do Google Docs partilhado ou uma wiki interna. Estas localizações alternativas podem ser mais acessíveis para utilizadores que não fazem parte da equipa da ADR. Outra opção é criar o seu ADR num repositório de controlo de origem, mas refletir as decisões importantes num wiki mais acessível.
O que se segue?
- O Centro de arquitetura na nuvem e a Google Cloud Framework bem arquitetada oferecem orientações e práticas recomendadas adicionais.
- Para algumas áreas que podem estar no seu ADR, consulte o artigo Padrões para apps escaláveis e resilientes.