Panoramica dei record decisionali dell'architettura

Per spiegare perché il tuo team dedicato all'infrastruttura o all'applicazione effettua determinate scelte di progettazione, puoi utilizzare i record decisionali dell'architettura (ADR). Questo documento spiega quando e come utilizzare gli ADR durante la creazione e l'esecuzione delle applicazioni su Google Cloud.

Un ADR acquisisce le opzioni chiave disponibili, i principali requisiti che determinano una decisione e le decisioni di progettazione. Archivia spesso gli ADR in un file Markdown vicino al codebase pertinente a tale decisione. Se un utente ha bisogno di comprendere il background di una decisione architettura specifica, ad esempio sul perché si utilizza un cluster Google Kubernetes Engine (GKE) a livello di area geografica, è possibile esaminare l'ADR e il codice associato.

Gli ADR possono anche aiutarti a eseguire applicazioni e servizi più affidabili. L'ADR ti aiuta a comprendere il tuo stato attuale e a risolvere eventuali problemi. Gli ADR creano inoltre una raccolta di decisioni di progettazione per aiutare a scegliere le decisioni e i deployment futuri.

Quando utilizzare gli ADR

Utilizzi gli ADR per tenere traccia delle aree chiave che ritieni importanti per il tuo deployment. Le seguenti categorie potrebbero essere incluse nei tuoi ADR:

  • Scelte di prodotti specifici, ad esempio tra Pub/Sub e Pub/Sub Lite.
  • Opzioni e configurazioni specifiche del prodotto, ad esempio l'uso di cluster GKE a livello di area geografica con Multi Cluster Ingress per applicazioni ad alta disponibilità.
  • Indicazioni architettoniche generali, come best practice per i manifest di Dockerfile.

Ecco alcuni esempi specifici che potrebbero chiederti di creare un ADR:

  • Come e perché configuri l'alta disponibilità (HA) per le istanze Cloud SQL?
  • Qual è l'approccio al tempo di attività dei cluster GKE? Utilizzi cluster a livello di area geografica? Utilizzi le versioni canary? Motiva la tua risposta.

Quando valuti i prodotti da usare, l'ADR contribuisce a spiegare ogni decisione. Nell'esempio di scelta tra Pub/Sub e Pub/Sub Lite, l'ADR potrebbe discutere di come i tuoi requisiti guidano la decisione sul prodotto da utilizzare. La seguente tabella illustra alcune delle differenze tra Pub/Sub e Pub/Sub Lite:

Funzionalità Pub/Sub Pub/Sub Lite
Replica dei messaggi Multizona in una singola area geografica Zona singola
Capacità Provisioning automatico eseguito Esegui il provisioning prima di utilizzare
Prezzi Paga per la capacità che utilizzi Paga per la capacità di cui esegui il provisioning
Archiviazione Nessun limite 30 GiB, 10 TiB per argomento Lite
Periodo di conservazione Fino a 7 giorni Nessun limite
Endpoint di servizio Globale e regionale A livello di area geografica
Spazio dei nomi delle risorse Globali Di zona
Routing dei messaggi Globali Di zona

I tuoi requisiti potrebbero includere il routing dei messaggi globale o la replica dei messaggi in più zone all'interno di un'unica area geografica. In questo esempio, l'ADR spiega che utilizzi Pub/Sub perché offre queste funzionalità, ma Pub/Sub Lite fornisce solo routing dei messaggi a livello di zona e replica dei messaggi a zona singola.

Puoi rivedere l'ADR man mano che il team si evolve e scopre di più sullo stack, così come le decisioni o le decisioni aggiuntive vengono prese o regolate. Se apporti aggiustamenti, includi la decisione precedente e il motivo della modifica. Questa cronologia tiene traccia di come l'architettura è cambiata in base all'evoluzione delle esigenze aziendali o alla necessità di nuovi requisiti tecnici o di soluzioni disponibili.

Le seguenti istruzioni ti consentono di sapere quando creare gli ADR:

  • In caso di problemi tecnici o domande, e non esiste una base di decisione, ad esempio una soluzione consigliata, una procedura operativa standard, un progetto base o un codebase.
  • Quando tu o il tuo team offrite una soluzione non documentata in un luogo accessibile al team.
  • Se esistono due o più opzioni di progettazione e vuoi documentare le tue convinzioni e i tuoi motivi.

Quando scrivi un ADR, è utile tenere a mente i potenziali lettori. I lettori principali sono i membri del team che lavorano sulla tecnologia coperta dall'ADR. Gruppi più ampi di potenziali lettori dell'ADR potrebbero includere team adiacenti che vogliono comprendere le tue decisioni, come i team di architettura e sicurezza.

Considera inoltre che l'applicazione potrebbe cambiare i proprietari o includere nuovi membri del team. Un ADR aiuta i nuovi collaboratori a comprendere il background delle scelte ingegneristiche effettuate. Un ADR semplifica anche la pianificazione di modifiche future.

Formato di un ADR

Un ADR tipico include una serie di capitoli. Gli ADR devono rispondere a ciò che ritieni importante per l'applicazione e la tua organizzazione. Alcuni ADR potrebbero contenere una pagina, mentre altri richiedono una spiegazione più lunga.

Il seguente esempio di ADR mostra come potresti formattare un ADR per includere le informazioni importanti per il tuo ambiente:

  • Autori e il team
  • Contesto e problema che vuoi risolvere
  • Requisiti funzionali e non funzionali da soddisfare
  • Potenziale percorso dell'utente critico (CUJ) che influisce sulla decisione
  • Panoramica delle opzioni principali
  • La tua decisione e i motivi alla base della scelta accettata

Per tenere traccia delle decisioni, puoi includere un timestamp per ogni decisione da mostrare quando viene presa la decisione.

Come funzionano gli ADR

Gli ADR funzionano meglio quando ingegneri, sviluppatori o proprietari di applicazioni possono accedere facilmente alle informazioni che contengono. Quando hanno una domanda sul motivo per cui qualcosa viene fatto in un certo modo, possono analizzare l'ADR per trovare la risposta.

Per rendere l'ADR accessibile, alcuni team lo ospitano in un wiki centrale accessibile anche ai proprietari dell'attività, anziché nel repository di controllo del codice sorgente. Quando qualcuno ha una domanda su una specifica decisione di progettazione, l'ADR è a tua disposizione per fornire risposte.

Gli ADR funzionano bene nei seguenti casi:

  • Assunzione: i nuovi membri del team possono saperne di più sul progetto e possono consultare l'ADR quando hanno domande mentre esaminano il codice dell'applicazione o altre applicazioni.
  • Passaggio di proprietà: se esiste un trasferimento di stack tecnologico tra i team, i nuovi proprietari possono esaminare le decisioni passate per comprendere lo stato attuale. L'ADR può inoltre contribuire a evitare la ripetizione degli stessi punti di discussione o a rivedere gli argomenti in futuro conoscendo il contesto storico.
  • Allineamento: i team possono allinearsi alle best practice dell'organizzazione quando gli ADR descrivono i motivi di alcune decisioni e vengono prese alternative.

L'ADR viene spesso scritta in Markdown per mantenerla leggera e basata su testo. I file di Markdown possono essere inclusi nel repository di controllo del codice sorgente con il codice dell'applicazione.

Memorizza le ADR vicino al codice dell'applicazione, possibilmente nello stesso sistema di controllo della versione. Man mano che apporti modifiche all'ADR, puoi controllare le versioni precedenti dal controllo dell'origine, se necessario.

Puoi anche utilizzare un altro mezzo, come un documento Google condiviso o un wiki interno. Queste località alternative potrebbero essere più accessibili agli utenti che non fanno parte del team di ADR. Un'altra opzione è quella di creare il tuo ADR in un repository di controllo del codice sorgente, ma rispecchiare le decisioni chiave in un wiki più accessibile.

Passaggi successivi